为什么 Skill 必须“像仓库一样被维护”
Skill 一旦开始被复用，就会出现三类成本：
- 使用成本：别人不知道怎么调用、怎么配置、有什么边界
- 变更成本：改了以后谁受影响、怎么回滚
- 排障成本：失败了找不到输入、输出、工具调用记录
解决方式不是“写更多文档”，而是“写对文档 + 放对位置 + 可版本化”。
推荐目录结构（可复制）
你可以把 Skill 当成一个小包，放在仓库的 skills/ 下：
skills/
pr_summary/
SKILL.md
examples/
input.json
output.json
evals/
cases.jsonl
rubric.md
tools/
tool_spec.json
changelog.md
如果你用 monorepo，也可以把它单独发包，但第一阶段不必。
SKILL.md 需要包含什么（最小集合）
建议至少包含以下小节（后面系列会逐步填充细节）：
- 概述：一句话说明“它做什么”
- 适用场景：3–5 条
- 不适用/拒绝：边界与禁区
- 输入/输出契约：字段与例子
- 依赖工具与权限：最小权限原则
- 失败类型与降级：枚举 + 处理策略
- 示例：至少 1 个完整输入输出
- 版本：当前版本与兼容性说明
示例：一份极简 SKILL.md
# PR Summary Skill
## What
Summarize a PR changes and risks for developers.
## Inputs
- repo: string
- pull_number: number
## Outputs
- summary: string
- risks: list
## Non-goals
- Do not decide whether to deploy.
## Tools
- github.get_pull_request (read-only)
## Failures
- TOOL_TIMEOUT -> retry with backoff
版本策略：用语义化版本保护使用者
给 Skill 做版本，至少遵循一个简单规则：
- 增加可选字段：minor
- 修改输出字段语义/删除字段：major
- 修复 bug 或文案：patch
Skill 的“接口”就是输入输出契约。只要契约不破，就能稳定迭代。
示例与回归：让 Skill 可被“复现”
强烈建议你为每个 Skill 保留：
examples/input.json：可复制的调用输入examples/output.json：你希望得到的输出结构evals/cases.jsonl：回归样本（后面会讲如何做自动评测）
工程化清单
- 目录结构固定，别人能猜到文件在哪
SKILL.md具备“能用”的信息，不写口号- 版本化输入输出契约
- 示例与回归样本齐全
常见坑
- 只有 README 没有例子：读者无法复现
- 只写 happy path：失败时没人知道怎么处理
- 不做版本：改一次坏一次
下一篇：工具调用（Tool Calling）设计：函数签名、参数校验、权限最小化。