用途
skill-maker 是一个用于创建和编辑 Claude Code 技能的流程工具。它将技能编写视为 "测试驱动开发（TDD）应用于流程文档"，主张：先编写测试用例（通过子代理运行压力场景），观察其失败（基线行为），再编写技能（文档），观察测试通过（代理遵守），最后重构（封堵漏洞）。其核心原则是：如果没有观察到代理在缺少该技能时失败，就无法确认该技能教的是正确的内容。
适用场景为创建或编辑技能时使用，要求在部署前用子代理进行测试，并迭代至无懈可击。
什么是技能
技能是以专门知识、工作流和工具扩展 Claude 能力的模块化包，类似特定领域的 "入门指南"。技能提供专门工作流、工具集成、领域专业知识、捆绑资源（脚本、参考、资产）。技能是可复用技术、模式、工具、参考指南；技能不是叙事、一次性解决方案或项目特定约定（项目特定约定应使用 CLAUDE.md）。
技能类型包括：技术（具体步骤）、模式（心智模型）、参考（API 文档/指南）、纪律约束（规则/要求）。创建时机：技术不显而易见、适用范围广、会被再次引用、确保跨实例行为一致。不应创建：一次性解决方案、有完善文档的标准实践、项目特定约定。
技能结构
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter: name (required), description (required), allowed-tools (optional)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - Executable code (deterministic, token-efficient)
├── references/ - Documentation loaded as needed (schemas, APIs)
└── assets/ - Files used in output (templates, boilerplate)
前置元数据规则：name 仅允许字母、数字、连字符（最多 64 字符）；description 使用第三人称，以 "Use when..." 开头，包含触发条件和目的（Anthropic 将 description 与可选 when_to_use 合并上限设为 1536 字符，应远低于此）；allowed-tools 可选，用于限制工具访问。写作风格使用祈使/不定式形式（"To accomplish X, do Y"），不使用第二人称。
渐进式披露：元数据始终加载（约 100 词）→ SKILL.md 在触发时加载（<5k 词）→ 资源按需加载。参考最佳实践：保持 SKILL.md 精简；若参考文件超过 1 万词，在 SKILL.md 中包含 grep 模式；避免在 SKILL.md 与参考文件间重复内容。
铁律
没有失败测试就不创建技能。这适用于新技能和编辑。若在测试前编写/编辑技能，应删除并重新开始，无例外——不因 "简单添加"、"仅一个章节" 或 "文档更新" 而例外。删除就是删除。
技能的 RED-GREEN-REFACTOR
RED：基线测试。在无技能的情况下运行压力场景，记录确切行为：代理做出了哪些选择、使用了哪些合理化说辞（逐字记录）、哪些压力触发了违规。方法：创建新对话/子代理 → 呈现场景 → 施加压力（时间限制、沉没成本、权威、疲劳）→ 记录失败。
GREEN：编写最小技能。针对那些具体合理化说辞编写技能，不为假设情况添加内容。在技能存在的情况下运行相同场景，代理应遵守，记录任何新违规。
REFACTOR：封堵漏洞。对每个新违规：识别合理化说辞 → 添加明确反制 → 重新测试直至无懈可击。对于纪律约束类技能：构建合理化表、创建 "红旗" 列表、添加 "无例外" 反制、处理 "精神与字面" 之争。
技能创建流程
第 1 步：理解。澄清具体使用示例。询问："这个技能应支持什么？"、"什么会触发它？"、"它将如何使用？" 在创建结构前进行 UltraThink：质疑根本问题——这是技能还是项目文档？什么是可复用的与一次性的？Claude 将如何发现它？代理会使用哪些合理化说辞？我们不包括什么？
第 2 步：规划资源。对每个用例：如何从零开始执行？重复执行时哪些脚本、参考或资产会有帮助？
第 3 步：初始化结构。mkdir -p dev-workflow/skills/skill-name/{scripts,references,assets}，并使用前置元数据模板创建 SKILL.md。
第 4 步：执行 RED-GREEN-REFACTOR。遵循上述循环：基线测试（RED）→ 编写针对失败的内容（GREEN）→ 封堵漏洞（REFACTOR）。技能内容必须回答：目的是什么？何时应使用？Claude 应如何使用？
第 5 步：部署后迭代。在实际任务中使用技能 → 注意困难 → 再次基线测试 → 更新 → 验证。
Claude 搜索优化（CSO）
注："CSO" 是 kisune 的框架，非 Anthropic 官方术语。底层机制是官方的：Claude 将用户意图与可用技能的前置元数据 description（及可选 when_to_use）匹配，以决定自动调用哪个技能。SKILL.md 正文不会被扫描用于匹配——在正文中填充关键词无助于激活，只有前置元数据参与匹配。
description 字段规则：以第三人称 "Use when..." 开头（非第二人称）；在 description 本身包含用户或代理会搜索的具体触发条件、错误消息和症状关键词（正文关键词对匹配无效）；描述技能解决的问题，而非实现细节；Anthropic 将 description 与 when_to_use 合并上限设为 1536 字符，建议 200-400 字符以留出余量。
命名规则：使用动词优先或动名词形式，如 creating-skills、testing-async-code、dispatching-agents；仅字母、数字和连字符，最多 64 字符；避免模糊标签（helper、utils、common）。
Token 效率目标：官方指南建议 SKILL.md 正文低于 500 行并采用渐进式披露（将大量内容移入 references/）。以下词数层级是 kisune 在此之上的启发式，非 Anthropic 政策。入门/引导类 <150 词；频繁加载类 <500 词；领域/参考类 <1000 词；纪律约束类最多 1500 词（合理化表使长度合理）。硬上限均为 SKILL.md 正文 500 行。若 SKILL.md 超过目标，将参考材料移入 references/ 子文件夹并链接。
交叉引用规则：仅按名称引用其他技能（如 "use dev-workflow:test-driven-development"）；避免 @filename.md 语法——它会强制将文件加载到上下文，破坏渐进式披露；当必须调用子技能时，使用 "REQUIRED SUB-SKILL:" 标记。
按技能类型测试
纪律类：用学术问题 + 压力场景（组合 3 种以上：时间、沉没成本、疲劳）测试，成功标准为代理在最大压力下遵守规则。技术类：用应用场景、变体、缺失信息测试，成功标准为代理将技术应用于新场景。模式类：用识别、应用、反例测试，成功标准为代理知道何时/如何应用（以及何时不应用）。参考类：用检索、应用、缺口测试，成功标准为代理找到并正确应用信息。
技能创建检查清单
使用 TaskCreate 为每项创建待办。RED 阶段：创建压力场景（纪律类技能组合 3 种以上压力）；在无技能情况下运行场景，逐字记录基线；识别合理化/失败的模式。GREEN 阶段：有效前置元数据（name 仅字母/数字/连字符；description 以 "Use when..." 开头、第三人称、与 when_to_use 合并 <1536 字符、建议 200-400）；全文包含用于搜索的关键词（错误、症状、工具）；清晰的概述与核心原则；针对 RED 中的具体基线失败；一个优秀示例（非多语言）；在技能存在下运行场景，验证遵守。REFACTOR 阶段：为新合理化添加反制；构建合理化表和红旗列表；重新测试直至无懈可击。质量检查：概述回答什么？何时？如何？快速参考表或要点；常见错误章节；无叙事故事；Token 数在目标内。部署：将技能提交到 git；必要时更新文档。
反模式
叙事示例（"In session 2025-10-03..."）——过于具体，不可复用；多语言稀释（example-js、example-py、example-go）——质量平庸，维护负担；通用标签（helper1、step3）——使用语义化名称；未测试技能——保证生产中出问题；模糊描述（"Helps with coding"）——Claude 无法知道何时激活。
与 Dev-Workflow 集成
利用现有技能：test-driven-development 用于测试、review 用于代码审查、brainstorming 用于设计探索。激活上下文：考虑技能在工作流中何时激活（规划、实现、质量）以及是自动激活还是需显式调用。按阶段的工具限制：规划用 Read、Write、Glob、Grep；实现用 Read、Write、Edit、Glob、Grep、Bash；质量用 Read、Grep、Glob。
底线
创建技能就是流程文档的 TDD。相同的铁律，相同的循环（RED → GREEN → REFACTOR），相同的收益。如果你对代码遵循 TDD，就应对技能也遵循它。