includewudi Skill Forge
将 Skill 写作从"凭感觉写 prompt"提升为工程化设计 —— 用经过验证的架构模式产出高质量 Skill。
按需加载子文档：本文档包含决策树和核心设计原则。详细参考见
references/子文档。
我需要做什么？（决策树）
⚠️ 每次新 Session → 先读 references/evolution-log.md 注入已知经验（§Phase 6.3）
你的目标
│
├─ 新建 Skill → §Phase 0→1→2→3→4→5
│ ├─ 模糊想法 → Phase 0 需求发现
│ ├─ 明确需求 → Phase 1 快速确认
│ └─ 对话提取 → Phase 1.3 回溯
│
├─ 改进/审查现有 Skill
│ ├─ 不被触发 → §CSO 优化
│ ├─ 效果差 → §Phase 4 迭代
│ ├─ 审查质量 → §质量验证三连
│ └─ 结构混乱 → 重写
│
└─ 只想了解原则 → references/design-patterns.md
⚠️ 完成后必做: §Phase 6 记录经验
核心设计原则（从 fast-edit 提炼）
这六条原则是高质量 Skill 的基础。详细案例见 references/design-patterns.md。
原则 1: 决策树路由
用户打开 Skill 后 5 秒内必须知道该做什么。
把"我该怎么做"变成 ASCII 决策树，放在最顶部。要点：树 3 层、叶节点可执行、分支互斥、标注 (DEFAULT) 兜底。
原则 2: 渐进式披露
信息量与需求成正比。不需要时，不要出现。
三层信息架构：
| 层级 | 载体 | 行数限制 | 内容 |
|---|---|---|---|
| L0 元数据 | YAML description |
~100 词 | 触发词、定位 |
| L1 主文档 | SKILL.md | <500 行 | 决策树 + 核心规则 |
| L2 子文档 | references/*.md |
无限制 | 详细模式、案例 |
关键：L1 只放违反会出错的规则；L2 通过"何时打开子文档"表按需加载。
原则 3: CLI 工具委托
确定性逻辑不要让 AI 做。交给脚本。
AI 擅长理解意图和生成内容，不擅长精确计数、格式校验、文件操作。能用脚本完成的确定性操作，都应委托 CLI。
原则 4: 验证闭环
每个动作都有验证步骤。没有验证 = 没有完成。
每个阶段需验证三连：①差异确认（改了什么）②语义检查（改对了吗）③集成验证（没破坏别的）。
原则 5: Token 压缩
每个 token 都是成本。用行号代替全文，用表格代替段落。
策略：规则→表格、流程→决策树、说明→代码注释、例外→⚠️ 内联标注、重复→见 §章节引用。
原则 6: 边界情况表格化
危险模式用查找表，不用散文。AI 需要精确匹配，不需要理解。
✅ 查找表（精确匹配） ❌ 散文（需要理解）
| 触发 | 风险 | 做法 | "当你遇到反引号时，
| `\`` | 执行 | batch| 需要特别注意，因为
| `$` | 展开 | batch| shell 会将其解释为
命令替换..."
设计要点：
- 表格列：
触发条件 | 风险/后果 | 正确做法 - 反面案例 + 正面案例成对出现
- 常见错误模式单独成表（如 off-by-one 错误表）
Phase 0: 需求发现
用户不知道自己想要什么，只有一个模糊的痛点或想法。 不要直接问"你要什么 Skill"。
快速诊断（3 问定位）
| 问题 | 诊断目标 |
|---|---|
| Q1: "具体是什么情况？描述一个最近的真实场景" | 真实痛点 vs 一次性需求 |
| Q2: "如果有一个按钮能一键解决，按下后会发生什么？"（投射法） | 用户理想终态 |
| Q3: "现在你怎么处理的？最烦哪个环节？" | 瓶颈定位 + 自动化空间 |
需求类型路由
| 用户状态 | 路由 |
|---|---|
| 真实重复痛点 + Q2 有明确终态 | → §Phase 1（需求已明确） |
| 想法太抽象（"我想更高效"） | → 深度发现（见下方） |
| 一次性小问题（频率 <1次/周） | → 直接解决，不建 Skill |
| 已有明确需求 | → §Phase 1.1（跳过此步） |
深度发现（想法抽象时，≤4 轮）
- 还原场景："上一次遇到这问题的完整经过？"
- 定位瓶颈："哪个环节卡最久？手动做了什么 AI 做不了的？"
- 验证频率："多久出现一次？每次处理多久？"
- 终态确认：呈现理解 → "所以你的核心需求是 X，对吗？"
⚠️ 一票否决：频率 <1次/周 → 直接帮解决，不建 Skill。
详细技巧（投射法、类比法、否证法、常见陷阱）见 references/need-discovery.md。
Phase 1: 意图采集
在写任何代码之前，确认三件事：用户要什么、给谁用、成功标准是什么。
1.1 快速确认（用户已有明确需求）
用户说"帮我写一个 X skill"时，确认以下字段：
| 字段 | 必填 | 示例 |
|---|---|---|
| Skill 名称 | ✅ | fast-edit |
| 一句话定位 | ✅ | "行号定位的文件编辑工具" |
| 目标用户 | ✅ | 通用 AI Agent / 特定团队 |
| 核心触发场景 (≥3) | ✅ | "编辑文件"、"保存粘贴"、"批量修改" |
| 依赖工具 | 可选 | CLI 脚本、外部 API、MCP |
| 已有参考 | 可选 | 类似 skill、文档链接 |
⚠️ 缺少必填字段 → 提问，不要猜测。
1.2 完整访谈（Phase 0 完成后补充采集）
访谈流程（≤5 轮对话）
│
├─ Q1: "这个 Skill 解决什么问题？没有它会怎样？"
│ → 提取: 核心价值、痛点
│
├─ Q2: "谁会用它？在什么场景下触发？"
│ → 提取: 目标用户、触发词
│
├─ Q3: "完成的标志是什么？怎么判断 Skill 好不好用？"
│ → 提取: 成功标准、验收条件
│
├─ Q4: "有没有类似的 Skill 或工具可以参考？"
│ → 提取: 参考架构、差异点
│
└─ Q5: "有什么硬性限制？（token 预算、工具约束、安全要求）"
→ 提取: 约束条件
1.3 回溯提取（从当前对话提取 Skill）
当用户在对话中解决了一个问题，想提取为 Skill 时：
- 回溯对话，提取：问题模式、解决步骤、验证方法
- 抽象为通用规则（去除特定文件名、变量名）
- 用 §1.1 的字段模板整理
- 询问用户确认 — 不要自动创建
Phase 2: SKILL.md 起草
2.1 结构模板
每个 SKILL.md 必须包含以下骨架（按顺序）：
---
name: {skill-name}
description: {CSO 优化的触发描述，见 §Description 优化}
---
# {Skill 名称}
{一句话定位 — 是什么 + 核心价值}
> **按需加载子文档**：本文档包含 ... 详细参考见 `references/` 子文档。
---
## 我需要做什么？（决策树）
{§原则1: 决策树路由}
---
## ⚠️ 安全守则（内联）
{只放违反会导致错误的规则，§原则2 L1 内容}
---
## 命令速查
{命令/操作的速查表，§原则5 token 压缩}
---
## 使用场景表
{场景 → 命令/操作映射}
---
## 验证三连
{§原则4: 验证闭环}
---
## 何时打开子文档
{子文档加载条件表}
---
## 文件结构
{目录树}
2.2 起草检查清单
写完初稿后，逐项检查：
- 决策树在最顶部？（§原则1）
- 树深度 ≤3 层？叶节点都是可执行动作？
- SKILL.md <500 行？超出内容移入
references/？（§原则2） - 安全守则只包含"违反会出错"的规则？
- 规则用表格/决策树，不用段落？（§原则5、6）
- 有验证三连？每个动作有对应验证步骤？（§原则4）
- 有子文档加载条件表？
- 命令速查用代码块，不用自然语言描述？
Phase 3: 测试验证
Skill 不经测试就发布 = 代码不跑测试就部署。
3.1 手动冒烟测试
在使用 eval 测试之前，先做基本的人工检查：
冒烟测试清单
│
├─ 触发测试: 用 3 种不同说法触发 Skill
│ ├─ 精确说法: "create a skill" → 应触发
│ ├─ 模糊说法: "help me write a good prompt file" → 应触发
│ └─ 负面测试: "what is a skill?" → 不应触发
│
├─ 决策树测试: 从树顶走到每个叶节点
│ └─ 每个叶节点的指令是否可执行？
│
├─ 完整流程测试: 用一个真实场景走完全流程
│ └─ 产出物是否符合预期？
│
└─ Token 预算测试: 检查 SKILL.md 总行数
├─ <500 行 → ✅
└─ >500 行 → 需要拆分到子文档
3.2 用 skill-creator 自动评估（Anthropic 官方）
官方 skill-creator 提供完整的评估基础设施：
# 1. 创建评估用例 (evals.json)
# skill-creator 会根据 SKILL.md 自动生成测试用例
# 2. 运行评估
# skill-creator 的 grader 会评分:
# - 触发准确率 (description 匹配)
# - 输出质量 (遵循 SKILL.md 指令)
# - 边界情况处理
# 3. 查看结果
# grading.json → 每个用例的分数
# benchmark.json → 聚合指标 + 方差分析
评估流程：
调用 skill-creator 进行评估:
- 提供: SKILL.md 路径 + 目标描述
- skill-creator 自动: 生成 evals → 运行 → 评分 → 输出报告
- 你只需: 阅读报告 → 决定是否迭代
⚠️ **不要自己重写 skill-creator 的评估逻辑** — 直接委托调用。详见 [官方仓库](https://github.com/anthropics/skills/tree/main/skills/skill-creator)。
Phase 4: 评估迭代
4.1 迭代决策树
评估结果
│
├─ 触发率 <70%
│ └─ 问题在 description → §Description 优化
│
├─ 触发率 OK，但执行效果差
│ ├─ AI 没遵循决策树 → 决策树分支不互斥，修复歧义
│ ├─ AI 遵循了但结果错 → 指令本身有问题，修改规则
│ └─ 部分场景好部分差 → 缺少边界情况表，补充 §原则6
│
├─ Token 超限（输出被截断）
│ ├─ SKILL.md >500 行 → 拆分到子文档
│ ├─ 段落太多 → 转为表格/决策树（§原则5）
│ └─ 重复内容 → 提取为命令速查
│
└─ 全部达标 → Phase 5: 打包发布
4.2 常见问题修复表
| 症状 | 诊断 | 修复 |
|---|---|---|
| Skill 从不被触发 | description 缺少触发词 | §Description 优化 |
| 触发了错误的 Skill | 触发词与其他 Skill 重叠 | 收窄 description，加负面排除词 |
| AI 读完 Skill 后不知道做什么 | 缺少决策树或决策树太深 | 重写决策树，≤3 层 |
| AI 跳过了安全规则 | 规则在子文档里，未内联 | 关键规则移入 SKILL.md 安全守则 |
| AI 用了错误的命令 | 命令速查不清晰或有歧义 | 用场景表明确映射 |
| 输出格式不符预期 | 缺少输出模板 | 添加 "Expected Output" 代码块 |
| 对简单场景过度复杂 | 没有快速路径 | 决策树加 DEFAULT 分支 |
Description 优化（CSO — Claude Search Optimization）
Description 是 Skill 的 SEO。AI 用它决定是否加载你的 Skill。
CSO 原则
好的 description
│
├─ 动作词开头: "Use when..."（告诉 AI 何时用）
│
├─ 核心场景 (≥3): 覆盖主要使用场景
│ "creating, designing, or improving AI skills"
│
├─ 触发短语: 用户可能说的话（越多越好）
│ "create a skill", "write a skill", "skill design",
│ "写技能", "技能设计", "优化技能"
│
├─ 动词变体: 同义动作覆盖
│ "create" / "write" / "build" / "design" / "improve"
│
├─ 负面排除: 不应触发的场景
│ "Do NOT use for general prompt writing or chatbot tuning"
│
└─ MUST/ALSO: 强调必须触发的场景
"MUST use when..." / "Also triggers on..."
Description 模板
Use when {核心动作1}, {核心动作2}, or {核心动作3} {目标对象}.
{补充能力描述}.
MUST use this skill whenever the user mentions {触发短语1}, {触发短语2},
{触发短语3}, or any intent to {概括性意图}.
Also triggers on {额外触发短语列表}.
优化检查清单
- 以 "Use when" 开头？
- 包含 ≥3 个核心触发场景？
- 包含中英文触发短语？（如面向中文用户）
- 包含 MUST 强制触发条件？
- 有负面排除避免误触发？
- 动词变体覆盖（create/write/build/design/improve）？
质量验证三连
发布前的最终关卡。三步全过才能发布。
Skill 写完了？
│
├─ Step 1: 结构检查（自动）
│ ├─ SKILL.md <500 行？
│ ├─ 有决策树？
│ ├─ 有验证三连？
│ ├─ 有子文档表？
│ └─ description 符合 CSO 模板？
│
├─ Step 2: 内容审查（人工/Agent）
│ ├─ 规则无歧义？（每条规则只有一种解读）
│ ├─ 边界情况有表格？
│ ├─ 反面案例 + 正面案例成对？
│ └─ 详见 references/quality-checklist.md
│
└─ Step 3: 实战评估（[skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)）
├─ 触发率 ≥80%？
├─ 执行质量评分 ≥7/10？
└─ 无严重错误（安全规则被跳过、输出截断）？
未通过？→ 回到 §Phase 4 迭代。
Phase 5: 打包发布
源码移入 Git 仓库 → 软链到 opencode/claude-code/gemini 的 skills 目录 → 注册 n-skills。发布前确认文件完整性 + 测试通过。详细命令、多平台目录规范和发布检查清单见 references/publishing.md。
Phase 6: 自我进化
设计完成后将新经验记录到 references/evolution-log.md。写入条件：通用、去重、置信度≥medium。类型：pattern / anti-pattern / edge-case / trigger-hack / architecture。生命周期：晋升（high + 引用≥3 → design-patterns.md）、过期（medium + 60天）、淘汰（总条目>30）。
⚠️ 每次新 Session 必先读 references/evolution-log.md — 按任务类型筛选注入。详细规则见该文件。
何时打开子文档
| 子文档 | 打开时机 |
|---|---|
references/design-patterns.md |
想了解 6 大原则的详细案例和反面模式 |
references/quality-checklist.md |
审查 Skill 质量时的完整检查表 |
references/need-discovery.md |
用户需求模糊、想法抽象，需要深度发现时 |
references/publishing.md |
执行打包发布时的目录规范、发布命令和发布检查清单 |
references/evolution-log.md |
每次 Session 开始时（注入已知经验）+ 设计完成后（记录新经验） |
agents/skill-reviewer.md |
需要自动化 Skill 审查时的 Agent 指令 |
反模式速查
| 反模式 | 后果 | 修正 |
|---|---|---|
| description 不写触发词 | 不被触发 | CSO 优化 |
| SKILL.md 超 500 行 | AI 遗忘尾部 | 拆分到 references/ |
| 用段落写规则 | AI 跳过或误解 | 转表格/决策树 |
| 无验证步骤 | 错误不被发现 | 加验证三连 |
| 决策树 >3 层 | AI 迷路 | 扁平化 |
| 只有正面案例 | AI 不知不该做什么 | 加 ❌ 反面案例 |
| 安全规则藏在子文档 | AI 不加载就跳过 | 关键规则内联 |
| 设计完不记录经验 | 同样的坑反复踩 | §Phase 6 |
| 一票否决未执行 | 为伪需求建 Skill | Phase 0 频率检查 |
文件结构
skill-forge/
├── SKILL.md # 本文档（主文档）
├── references/
│ ├── design-patterns.md # 6 大原则详细案例
│ ├── quality-checklist.md # 完整质量检查表
│ ├── need-discovery.md # 需求发现技巧（投射法/类比法/否证法）
│ ├── publishing.md # 打包发布详细规范
│ └── evolution-log.md # 进化日志（自我进化机制）
└── agents/
└── skill-reviewer.md # Skill 审查 Agent 指令