本文以一个真实案例——「SEO 体检」技能的诞生全过程——总结创建 SKILL 需要做的工作、用到的指令，以及踩过的坑。适合想把自己的重复性工作流固化成可复用技能的人。
一、什么是 SKILL，为什么要创建
SKILL 是把一套多步骤工作流固化下来的可复用能力包。一次做好，之后一句话就能触发整套流程，不必每次重新交代。
一个 SKILL 本质上是一个文件夹：
skill-name/
├── SKILL.md ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/ ← 可选：可复用的代码脚本
│ └── *.py
└── evals/ ← 可选：测试用例
└── evals.json
适合做成 SKILL 的信号：这件事你会重复做、步骤 ≥2、有明确产出物、换个对象（URL/客户/项目）还能用。
二、创建 SKILL 的整体流程（5 步）
创建技能本身也有一个"元技能"来引导。核心是这 5 步：
| 步骤 | 做什么 | 用到的指令/工具 |
|---|---|---|
| 1. 先把工作流真正跑通一遍 | 用真实任务完整做一次，产出真实成果 | 正常对话即可 |
| 2. 确认技能骨架 | 定技能名、显示名、触发词、输入项、图标 | 与 AI 确认 |
| 3. 提取会话数据 | 自动抽取用过的工具、生成骨架 | extract_session_data |
| 4. 写 SKILL.md | 补全流程、经验、脚本 | AI 生成，人工审核 |
| 5. 保存 + 测试 | 存入技能库、生成测试用例 | save_skill + generate_skill_evals |
三、逐步拆解：每一步具体做什么
步骤 1：先跑通工作流（最重要）
别急着建技能。先拿一个真实需求完整做一遍，比如："帮我检查这个网页的 SEO"。在这个过程中：
- 明确输入是什么（一个 URL？一批 URL？）
- 明确产出是什么（一份报告？什么格式？）
- 记录每一步用了什么能力（打开网页、跑代码、生成 Excel……）
实战教训：我们的 SEO 技能，是先真刀真枪审查了某企业官网的多个页面、反复调整报告格式后，才提炼成技能的。中途用户不断提要求（加 Bing 标准、核实官方来源、改成执行矩阵、拆成两阶段……），这些都成了技能里最有价值的部分。
步骤 2：确认技能骨架
跟 AI 说清楚（或让它建议）：
| 项目 | 说明 | 示例 |
|---|---|---|
| 技能名 | 小写连字符，内部标识 | seo-audit-skill |
| 显示名 | 给人看的名字 | 「SEO 体检」 |
| 触发词 | 哪些话该激活它 | "SEO体检 / 网站优化 / 检查页面SEO" |
| 输入项 | 每次会变的东西 | page_url、audit_scope |
| 图标 | 一个 emoji | 🔍 |
步骤 3：提取会话数据
这一步由工具自动完成：扫描刚才跑通的会话，抽出用过的工具清单，生成一个带 YAML frontmatter 的 SKILL.md 骨架。你只要提供步骤 2 定好的：技能名、触发词、输入项、显示名、图标。
指令：extract_session_data
步骤 4：写 SKILL.md（核心创作）
在骨架基础上补全以下部分：
① frontmatter（文件头）
---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
- name: page_url
description: "要体检的页面网址"
required: true
scripts: [seo_audit.py, seo_matrix.py]
---
② Overview
2–3 句说清做什么、何时用。
③ Workflow（分步骤）
每步标注模式（deterministic 固定动作 / agentic 需判断）、输入、输出、验证方式、失败怎么办。多讲"为什么"，少写死板的"必须/禁止"——执行技能的 AI 更吃"讲道理"。
④ Output
最终产出长什么样，定义清楚格式。
⑤ Lessons Learned（经验）
这是技能质量的分水岭，分四块：
- Do：哪些做法有效
- Don't：哪些坑别踩
- Common Failures：常见错误 + 应对
- When to Ask the User：什么时候该停下来问人
实战教训：我们这个技能的 Lessons 里写满了真实踩过的坑——中文别用\uXXXX转义、写 CSV 用utf-8-sig防 Excel 乱码、图片 alt 缺失率异常高多半是懒加载误报（要标"待核"而非直接判缺）、部分域名会屏蔽批量抓取，需用浏览器验证……这些"血泪"让技能下次跑得更稳。
⑥ 脚本（可选但强烈推荐）
如果流程里有重复写的代码，抽成脚本放 scripts/，在 SKILL.md 里引用。我们把"页面信号采集 JS"和"多页矩阵生成"做成了两个脚本，保证输出格式每次一致。
步骤 5：保存 + 测试
- 保存指令：
save_skill（技能名 + 完整 SKILL.md + 脚本） - 生成测试：
generate_skill_evals（自动造几个测试用例） - 然后真跑一次验证——我们分别用单页、多页两种场景实测，确认能识别真实问题（比如揪出若干 404 坏链接、发现社交分享标题与页面标题不一致）。
四、创建后如何迭代与分发
迭代改进
指令：load_skill_for_improvement。技能不是一次成型的。用了几次后按需改进：
- 改流程、加输出格式、调触发词
- 保存时用同一个技能名即可原地覆盖（会自动备份旧版）
实战：我们这个技能迭代了很多轮——加 Bing 标准、改执行矩阵格式、拆成两阶段、加 Excel+Markdown 双输出、修列名对齐样例、最后改名。每轮都是load_skill_for_improvement→ 改 →save_skill覆盖。
重命名
改 frontmatter 里的 name 和 display_name，用新名 save_skill，再删掉旧技能文件夹。
打包分发
把整个技能文件夹压成 zip，即可备份、迁移到别的电脑、或分享给同事（放进对方的 skills 目录）。
跨工具移植
如果要在别的 AI 工具（ChatGPT/Claude/Gemini）用，需要"去平台化"：把专有工具名改写成通用能力描述（"打开网页""运行代码"），并把脚本内嵌成自包含的 Markdown，即可整段粘贴为系统提示/自定义指令。
五、常用指令速查
| 指令 | 作用 | 用在 |
|---|---|---|
extract_session_data | 从会话抽取骨架 | 创建·步骤 3 |
save_skill | 保存/覆盖技能 | 创建·步骤 5 / 迭代 |
generate_skill_evals | 生成测试用例 | 创建·步骤 5 |
load_skill_for_improvement | 载入技能以改进 | 迭代 |
六、避坑清单（来自真实踩坑）
- 先跑通再固化——别凭空写技能。
- 输入只放会变的——固定值写死在流程里。
- Lessons Learned 要写满真实经验——这是技能能不能"越用越稳"的关键。
- 重复代码抽成脚本——保证输出格式一致、省 token。
- 保存后必测——真跑一次单页 + 多页，验证它能识别真实问题。
- 编码坑（若涉及中文/代码生成）：写文件用
encoding="utf-8"，CSV 用utf-8-sig，别用\uXXXX转义，PDF 中文用内置 CID 字体。 - 迭代用同名覆盖——
name不变，自动备份旧版。
结语
创建 SKILL 的本质是：把一次成功的工作流，连同其中的判断与教训，一起封装成"下次一句话就能重来"的能力。 做得好的技能，不只是记录了步骤，更记录了"怎么把这件事做对"的经验。
先把事情做漂亮，再让它可复用——这就是创建 SKILL 的全部心法。
