write-a-skill

用途

write-a-skill 用于编写单个新技能：为已有技能树中的某一项能力产出一个 SKILL.md，以及可选的捆绑参考资料和脚本，遵循 Anthropic 的渐进式披露约定。其编写循环为：收集需求、按 SKILL.md 契约起草、与用户评审、精炼。核心原则是一个技能只关注一件事，一个技能一个目录。

范围界定

write-a-skill：在已有技能树中为某一项能力编写一个 SKILL.md。
Repo onboarding：面向整个仓库的入门引导，搭建 AGENTS.md 和项目约定。
skill-creator:skill-creator：本技能所应用的上游方法论；如需权威契约请查阅它。

编写循环

收集需求——在起草前先明确决策：
- 能力边界：该技能覆盖什么任务，明确不覆盖什么？
- 触发短语：哪些用户短语或上下文应加载它？
- 确定性：是否有操作足够确定，可以放进脚本而不是每次重新生成散文？
- 捆绑参考资料：需要包含哪些文档、模式或示例？
- 静态保证上下文：语言家族（Rust、TypeScript、Python、Kotlin、Go、OCaml 等）——影响测试章程范围。
起草 SKILL.md——按下方契约撰写。正文保持简洁、面向决策。
与用户评审——呈现草稿，暴露有歧义的决策，并精炼。
验证——运行任何捆绑的 evals.json 用例；有针对性地重读 SKILL.md，确认描述触发条件和正文一致。

目录布局

skill-name/
  SKILL.md              # 契约；必需
  references/           # 按需加载的更深文档
    REFERENCE.md
    EXAMPLES.md
  scripts/              # 确定性辅助脚本
    helper.{ts,py,sh}
  evals.json            # 触发 / 行为评估

SKILL.md 中的引用路径使用 references/X.md，绝不使用 ./X.md。

SKILL.md 契约

---
name: skill-name
description: <技能做什么>。 <何时触发——具体短语或上下文>。
---

<一句话祈使式总结该技能的定位。>

## <章节> — 简洁、面向决策的散文

<以祈使语气撰写正文，并附简短理由。≤200 行。>

Frontmatter 规则：

name——kebab-case，与目录名一致。
description——强触发：说明做什么以及何时触发。最多 1024 字符。第三人称。第一句陈述能力；第二句陈述触发条件。
disable-model-invocation: true——若源中存在则原样保留；不要编造。

三级渐进式披露

描述（frontmatter）——harness 唯一读取以决定是否加载的文本。触发条件必须具体。
SKILL.md 正文——被选中后加载一次。保持 ≤200 行；深度内容下放到 references。
references/ 和 scripts/——当正文链接到它们时按需加载。

强触发描述示例

弱：Helps with documents.
强：Extract text and tables from PDF files, fill forms, merge documents. Trigger when user mentions PDFs, forms, or document extraction.

脚本与散文

当操作是确定性的、且否则每次调用都会重新生成相同代码时，添加脚本。当工作是模型每次必须重新执行的上下文推理时，跳过脚本。

语气与禁用工具

使用祈使语气或第三人称。不要使用“you/your”称呼对象。英语要求：语法正确的英语，保留冠词。禁用工具不得出现：优先使用 bat -P -p -n、fd、git grep、ast-grep、srgn、hyperfine、difft、eza、rip，而非其被禁用的对应工具。