# Skill Forge

> Skill Forge

- Skill: `includewudi/skill-forge` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add includewudi/skill-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/includewudi/skill-forge/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: includewudi (https://skillmd.com/u/includewudi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/includewudi/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 必须包含以下骨架（按顺序）：

```markdown
---
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 官方](https://github.com/anthropics/skills/tree/main/skills/skill-creator)）

官方 skill-creator 提供完整的评估基础设施：

```bash
# 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 指令
```