write-a-skill

用途

write-a-skill 用于编写单个新技能：产出一个 SKILL.md，以及可选的捆绑参考资料（references）和脚本（scripts），遵循 Anthropic 的渐进式披露约定。它面向的是在已有技能树中为某一项能力撰写技能文档的场景。

范围界定

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: <what the skill does>. <when to trigger it — concrete phrases or contexts>.
---

<One-line imperative summary of the skill's posture.>

## <Section> — terse decision-oriented prose

<Body in imperative voice with brief why. ≤200 lines.>

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，而非其被禁用的对应工具。