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