skill-forge

name	skill-forge

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 轮）

1. 还原场景："上一次遇到这问题的完整经过？"
2. 定位瓶颈："哪个环节卡最久？手动做了什么 AI 做不了的？"
3. 验证频率："多久出现一次？每次处理多久？"
4. 终态确认：呈现理解 → "所以你的核心需求是 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. 回溯对话，提取：问题模式、解决步骤、验证方法
2. 抽象为通用规则（去除特定文件名、变量名）
3. 用 §1.1 的字段模板整理
4. 询问用户确认 — 不要自动创建

---

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 进行评估:

1. 提供: SKILL.md 路径 + 目标描述
2. skill-creator 自动: 生成 evals → 运行 → 评分 → 输出报告
3. 你只需: 阅读报告 → 决定是否迭代

⚠️ **不要自己重写 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 指令