Skills 编写规范与经验指南

写在最前面：实际上，绝大部分的skill创作都可以通过安装skill-creator后，再和Agent对话跑完整个流程，直接要求Agent将整个流程处理成skill。

1. Skill 是什么

一个 skill 是一个文件夹，里面至少有一个SKILL.md。这个SKILL.md就是给模型（Claude / 其他 agent）看的说明书，告诉它：

• 什么时候应该调用这个 skill（触发条件）；
• 怎么做这项专门的任务（步骤、模板、脚本、检查清单）；
• 不该做什么（反模式、边界）。

Skill 与 prompt 的差别在于：prompt 是一次性输入，skill 是可复用、可版本化、可迭代评估的能力单元。它可以被打包为.skill文件、发布到 marketplace、被多个 agent 共享。

Skill 与 tool（工具）的差别在于：tool 是模型可以直接调用的动作接口；skill 是指导模型如何组合 tools 完成一类工作的知识包。一个 skill 里通常会自带若干脚本作为 “sub-tools”，但真正的价值在文档本身。

简言之：Skill = 一个装着 SKILL.md 的文件夹，用来把某项专门知识"装配"到模型上下文里。

2. Skill 的物理结构

官方推荐的最小与完整目录结构：

skill-name/ # 目录名建议 kebab-case ├── SKILL.md # 必需：YAML frontmatter + Markdown 正文 ├── LICENSE.txt # 强烈建议：非必需，用于公开发布时的免责与产权的声明 ├── scripts/ # 可选：可执行的确定性脚本（Python/Node/Bash） │ ├── main_tool.py │ └── utils.py ├── references/ # 可选：按需加载的深度文档 │ ├── advanced.md │ └── schemas.md ├── assets/ # 可选：产物中直接使用的静态资源 │ ├── template.html │ └── fonts/ ├── examples/ # 可选：范例、样例输入输出 │ └── sample-input.md ├── templates/ # 可选：起始模板（如 HTML/JS 骨架） ├── agents/ # 可选：子 agent 的 system prompt 片段 │ └── grader.md └── requirements.txt # 可选：Python 依赖清单

命名习惯（与上面目录树严格对应）：

约定 1：文件夹名、namefrontmatter 字段、marketplace 中注册的 skill 名，三者严格一致（如pdf、docx、skill-creator）。

约定 2：把 skill 视为「一个可移植的最小单元」——不要在 SKILL.md 里引用文件夹外的路径。

3. 渐进披露 - Skill 的核心设计哲学

Skill 的加载分三级，写作时必须按这三级来切分内容：

核心原则：L2 是路由，不是百科全书。当 SKILL.md 快要超过 500 行、或某一节篇幅过大时，就要把细节剥离到references/或examples/，SKILL.md 里只留一句「如果要做 X，请阅读references/x.md」。

4. YAML Frontmatter 规范

SKILL.md顶部必须以---分隔的 YAML 块开始。规范字段如下：

4.1 必填字段

---name:my-skill-name# 唯一标识；kebab-case；与目录名一致description:>一句/一段说明「这个 skill 做什么 + 什么时候应该被触发」。 这是 skill 唯一的触发信号，务必写好。---

4.2 可选字段

version:语义化版本号# 建议字段；当前各客户端尚未统一支持，但有助于团队内版本管理license:Complete terms in LICENSE.txt# 或 "Proprietary"compatibility:...# 依赖工具/环境（较少使用）

4.3description—— 唯一的触发信号

模型是否加载这个 skill，几乎完全由description决定。因此这一字段既是"电梯陈述"，也是"路由规则"。

优质 description 的六个特征：

1. 主动"推销"——skill 天然容易 undertrigger（模型不主动使用）。写法上略带"push"：

   “Make sure to use this skill whenever the user mentions dashboards, data visualization, or wants to display any kind of company data — even if they don’t explicitly ask for a ‘dashboard.’”

2. 列出触发词/触发场景——把用户可能说的短语列出来，例如PRD / RFC / design doc / write a doc（doc-coauthoring）。

3. 列出应当跳过的场景——用Do NOT trigger when …显式地划边界（xlsx、docx）。

4. 包含 TRIGGER / SKIP 路由头——参考claude-api：

   TRIGGER — read BEFORE opening the target file … SKIP only when another provider is being worked on …

   这把 description 从"元数据"升级为"路由器"。

5. 对创作型 skill：加版权提醒——algorithmic-art / canvas-design / brand-guidelines都在 description 里加：

   “Create original … rather than copying existing artists’ work to avoid copyright violations.”

6. 保持"完整语境"——不要写 “Format PDF”，而写 “Fill out interactive PDF forms, extract text/tables from PDFs, redact content, or convert to images. Trigger whenever a.pdffile is mentioned.”

4.4 关于 name 的约束

• 全小写，用连字符分隔单词（kebab-case）。
• 不与其他 skill 冲突；建议先用 marketplace 检索。
• 与目录名严格一致；重命名时同步.claude-plugin/marketplace.json。

5. SKILL.md 正文的常见骨架

正文没有强制结构，但仓库中反复出现的高价值骨架有以下几种模块，可按需拼装：

5.1 顶部 Quick Reference / 决策表

在正文开头放一张任务 → 使用哪个方法/文件的表格。docx、pptx、claude-api等 skill 都用了这套。

## Quick Reference | 任务 | 用什么 | | --- | --- | | 填写可交互 PDF 表单 | 阅读 `forms.md` | | 从 PDF 中提取文本 | 使用 `pdfplumber` | | 生成新 PDF | 使用 `reportlab` |

价值：模型进入 skill 后，第一眼就能路由到正确的子路径，而不必读完整个文档。

5.2 Overview / When to use

一段 3–5 行的自我介绍：这个 skill 干什么、适用什么场景、不适用什么场景。放在 Quick Reference 之下、正式流程之上。

5.3 Workflow / Process（阶段化流程）

复杂的 skill 用编号阶段拆分：

• mcp-builder用 4 个 Phase（Deep Research → Design → Implement → Evaluate）；
• doc-coauthoring用 3 个 Stage（Context Gathering → Refinement → Reader Testing）；
• algorithmic-art用 5 个大写阶段（ALGORITHMIC PHILOSOPHY CREATION → DEDUCING THE CONCEPTUAL SEED → …）。

每个阶段下要写清：目的、动作、检查点、进入下一阶段的准入条件。

5.4 Common Pitfalls / Anti-patterns

在 skill 末尾（或阶段内）显式列出过去失败过的写法。这一节的价值极高：

• docx：14 条 “Critical Rules for docx-js”；
• pptx：NEVER use accent lines under titles；
• web-artifacts-builder：反 “AI slop”（避免居中布局、紫渐变、Inter 字体）；
• webapp-testing：DO NOT read the source until you try running the script first。

5.5 QA / 自检 checklist

给出模型可对照打勾的 markdown checklist（xlsx的 “Formula Verification Checklist”）。让 QA 变成可执行动作而不是抽象要求。

5.6 Reference Files 索引

在末尾列出所有 L3 附属文件与何时读取：

## Reference Files - `references/schemas.md` — JSON 结构参考 - `agents/grader.md` — 判分子 agent 的 prompt

6. 六种常见 Skill 形态（模式库）

6.1 Router 型（超轻量路由器）

代表：internal-comms（32 行）
适用：一个大主题下有多个并列子领域，每个子领域独立成文。
结构：When to use → How to use（3 步：识别 → 加载 examples/xxx.md → 执行）→ Keywords。
优点：SKILL.md 极小，永远不会撑爆 L2 上下文。

6.2 Reference 型（长期查阅手册）

代表：claude-api（578 行）、brand-guidelines
适用：知识密集，模型会反复回来查阅。
结构：Quick Reference 表 → 分主题参考 → Common Pitfalls。
关键技巧：

• description 中带TRIGGER/SKIP路由头；
• 支持"子命令"（如/claude-api migrate）；
• 显式 pin 版本（“ALWAYS useclaude-opus-4-8— non-negotiable”）；
• 包含 API drift 表（stale vs current）。

6.3 Workflow 型（多阶段流程）

代表：skill-creator、mcp-builder、doc-coauthoring、webapp-testing
适用：任务需要多步骤、有明确产出物。
结构：分 Phase / Stage 编号；每阶段有目标、动作、退出条件。
关键技巧：

• 用 ASCII 决策树（webapp-testing）表达路径选择；
• 用"环境分支"处理有/无 subagent 场景（doc-coauthoring、pptx）；
• 用红队框架：“Assume there are problems. Your job is to find them.”（pptx）。

6.4 Creative / Philosophy 型（创作类）

代表：algorithmic-art、canvas-design、frontend-design
适用：输出是艺术/设计，需要模型有诠释空间。
结构：先写"创作理念"（4–6 段风格宣言），再写"执行细节"。
关键技巧：

• Philosophy + Execution 两步法：先让模型写一份小型"艺术运动宣言"，再基于宣言生成产物；
• 明确 FIXED vs VARIABLE 部分（“模板结构不动，只替换算法/参数”）；
• 反 AI slop：显式列出模型的默认平庸倾向并禁用（frontend-design的三种默认外观、web-artifacts-builder的紫渐变+Inter）。

6.5 Human-in-the-loop 型（需要用户参与）

代表：theme-factory
适用：产出前必须由用户挑选/确认。
结构：4 步——向用户展示 showcase → 请用户选择 → 等待选择 → 应用选择。
关键技巧：把"等待用户"作为流程的合法节点，而不是"打断"。

6.6 Toolkit / Script-first 型（脚本包）

代表：slack-gif-creator、docx、pdf、pptx、xlsx
适用：任务本质是数据处理/文件生成，脚本比 prompt 更可靠。
结构：SKILL.md 说明何时调哪个脚本；具体逻辑在scripts/。
关键技巧：

• 让脚本--help自解释；
• 明确要求"不要读脚本源码"（webapp-testing）以省 token；
• 提供"字段/颜色/格式"的固化规范（xlsx的财务模型颜色约定：蓝=输入、黑=公式、绿=跨表、红=外部、黄=关键假设）。

7. 写作风格与 prompt 语言技巧

Skill 的正文本质是给模型看的 prompt。

7.1 祈使句 + 说明"为什么"

避免堆砌全大写MUST/NEVER，而是解释这么做的原因。模型有 theory of mind，理解原理后能举一反三；纯命令则只在原例上生效。

反例：NEVER use requests library.
正例：Prefer httpx over requests because we need async support and requests is not maintained upstream.

只有在真的踩过多次坑、必须硬性阻止时，才使用NEVER/ALWAYS全大写形式。

7.2 ❌/✅ 对照示例

给出错误写法与正确写法并列（docx、xlsx、web-artifacts-builder广泛使用）：

❌ WRONG: `ws.cell(row=10, column=2).value = 15234.5` ✅ CORRECT: `ws.cell(row=10, column=2).value = "=SUM(B2:B9)"`

对照示例比抽象规则的 signal 强 5 倍。

7.3 “Read this file when X” 指针

L2 到 L3 的路由必须具体、条件化：

If you need to fill out a PDF form, read `forms.md` and follow its instructions.

避免：“see references for more info”（模糊、模型不会真的去读）。

7.4 STEP 0 强前置

对于容易被跳过的关键前提（读模板、跑 --help），显式立成 “STEP 0”：

### ⚠️ STEP 0: READ THE TEMPLATE FIRST ⚠️ Do not start coding until you have read `templates/base.html` in full.

7.5 环境分支

skill 可能运行在 Claude Code、Claude.ai、Cowork、其他 agent 环境中，用If access to sub-agents is available:/If not:显式分叉，避免模型走错路径。

7.6 反过度积极

有时需要"叫模型别做"：

• web-artifacts-builder：“avoid testing the artifact upfront as it adds latency”
• docx：“Do not write Python scripts — use the Edit tool directly”
• webapp-testing：“DO NOT read the source until you try running the script first”

模型默认过度积极，显式的"少做"指令能省大量 token。

7.7 Tone 元指令

想控制模型对用户说话的语气，就写一节Tips for Effective Guidance（doc-coauthoring）：

“Be direct and procedural. Don’t try to ‘sell’ the approach — just execute it.”

7.8 版本 pinning

对易漂移的字段（模型 ID、SDK 版本）明确 pin 值并说明"non-negotiable"。参考claude-api。

7.9 关键词尾巴

在文末列一个Keywords:短列表（internal-comms、brand-guidelines），补充 description 中未覆盖的同义词/触发词。

8. 脚本、模板与资源目录的约定

8.1 scripts/ 的黄金规则

1. 每个脚本都有--help——模型第一步永远是python scripts/foo.py --help。
2. 默认黑箱调用，不读源码——脚本可能几百上千行，读进上下文会拖慢模型。SKILL.md 应显式说 “call as black-box; do not ingest source unless customization is required”。
3. 脚本命名保持稳定——重命名等于破坏 skill 使用者的记忆。
4. 在 SKILL.md 里给出可复制粘贴的完整命令：

   python scripts/aggregate_benchmark.py<workspace>/iteration-N --skill-name<name>

5. 依赖用requirements.txt（Python）或package.json（Node）声明。

8.2 references/ 的黄金规则

• 单文件超过 300 行时必须在文首放 TOC；
• 每个文件的开头写一句"什么时候读这个文件"；
• 交叉引用其他 references 时使用相对路径references/xxx.md。

8.3 assets/ 的黄金规则

• 仅存放最终产物中直接使用的资源（模板、字体、图标）；
• 大二进制（字体、PDF）用 LFS 或子仓库。

8.4 templates/ 的黄金规则

• 明确 FIXED（不可改）与 VARIABLE（可替换）区域；
• 在 SKILL.md 中把这一区分写死。

9. Skill 的评估与迭代闭环

skill-creator沉淀了一套完整的「写 → 测 → 评 → 改」的闭环，值得作为标准工作流引入你自己的 skill 项目：

9.1 触发（description）测试

从"用户是否会说这句话时期望被触发"角度，构造 20 条 query（一半 should-trigger、一半 should-not-trigger），near-miss 越多越有信息量。用run_loop.py迭代优化 description。

关键点：should_not_trigger必须是"貌似相关但其实不该触发"，而不是显然无关的问题——否则测试没有 signal。

9.2 输出（内容）评估

对每个测试 prompt，同时跑：

• with-skill：加载 skill 的版本；
• baseline：不加载 skill（新 skill）或加载旧版（改进 skill）。

结果按iteration-N/eval-K/{with_skill,without_skill}/outputs/组织。

9.3 断言（assertions）设计

每条测试 prompt 配套若干断言（grading.json中的expectations）：

• 命名要读得懂——"输出包含 SUM(B2:B9) 公式"好过"assertion_3"；
• 可编程校验的断言优先——写脚本判分而不是"眼球判分"；
• 主观类断言不要硬凑——设计/写作类交给人类打分。

9.4 Benchmark 聚合与查看

benchmark.json的 schema（详见skill-creator/references/schemas.md）字段名严格：configuration必须是"with_skill"或"without_skill"；pass_rate/time_seconds/tokens必须嵌套在result下。

用eval-viewer/generate_review.py生成的 HTML 视图给人类看，让他填feedback.json做定性反馈。

9.5 迭代规则

1. 从反馈里泛化——不要只修 3 个测试例，要理解背后共通的失败模式；
2. 保持 prompt 精简——如果一段话没贡献信号，删掉；
3. 解释"为什么"——见 §7.1；
4. 横向发现重复劳动——如果 3 次运行都独立写了同一个脚本，把它内置到scripts/。

9.6 打包发布

python scripts/package_skill.py<path/to/skill-folder>

产出.skill文件（本质是 zip）。marketplace 通过.claude-plugin/marketplace.json注册。

10. 新手 30 分钟上手流程（Quick Start）

如果你是第一次写 skill，按下面顺序做，30 分钟内可跑通闭环：

步骤 1（3 分钟）：确定 skill 形态

对照 §6，问自己三个问题：

1. 有多少子领域？多 → Router 型；少 → Workflow 型。
2. 是流程还是查阅？流程 → Workflow；查阅 → Reference。
3. 是创作还是确定性？创作 → Philosophy；确定性 → Toolkit。

步骤 2（5 分钟）：新建目录 + 复制模板

mkdir-pmy-skillcptemplate/SKILL.md my-skill/SKILL.mdcpLICENSE.txt my-skill/LICENSE.txt# 如需

步骤 3（10 分钟）：写 SKILL.md

按下面骨架填空：

--- name: my-skill description: > 【一句话说做什么】。Trigger whenever 【触发条件A】、【触发条件B】、 or 【触发条件C】. Do NOT trigger when 【排除条件】. license: Complete terms in LICENSE.txt --- # My Skill ## Overview 【3–5 行自我介绍】 ## Quick Reference | 任务 | 使用 | | --- | --- | | ... | ... | ## Workflow ### Step 1: 【动作】 ### Step 2: 【动作】 ## Common Pitfalls - ❌ ... - ✅ ... ## Reference Files - `references/xxx.md` — 何时读它

步骤 4（5 分钟）：写 2–3 条测试 prompt

{"skill_name":"my-skill","evals":[{"id":1,"prompt":"真实用户会说的话1","expected_output":"…"},{"id":2,"prompt":"真实用户会说的话2","expected_output":"…"}]}

步骤 5（5 分钟）：跑一次 with_skill vs without_skill

用skill-creator提供的脚本或手动 spawn 两个子任务。看两组输出的差别，决定：

• 如果 with_skill 明显更好 → 进入迭代；
• 如果几乎一样 → skill 没提供信号，回炉重写；
• 如果 with_skill 更差 → skill 在误导模型，找出误导点。

步骤 6（2 分钟）：写下改进方向

在 skill 目录旁开一个NOTES.md，记录本轮观察 + 下一版打算改哪里。进入下一轮迭代。

11. 常见反模式（Anti-Patterns）

12. 参考内容

• Anthropic public claude skills
• Specification for Agent Skills