skill-authoring

技能编写指南

不适用场景

• 评估已存在的技能（使用 abstract:skills-eval）
• 编写钩子（使用 abstract:hook-authoring）
• 验证技能是否触发（使用 abstract:subagent-testing）

概述

编写有效的 Claude Code 技能需要采用测试驱动开发（TDD），并运用合规研究中的说服原则。我们将技能编写视为需要通过实证验证的流程文档，而非单纯的理论指导。技能是旨在以可衡量的方式改变模型行为的行为干预措施。

采用 TDD 可确保技能针对测试中发现的实际失效模式。优化描述可提升发现率，而模块化结构支持渐进式披露，以管理令牌用量。它会说明意图、约束和退出标准，并将两者之间的执行路径留给实际开展工作的会话。modules/persuasion-principles.md 规定了强度预算，用来决定每条陈述在三者中属于哪一种。

铁律

没有先失败的测试，就不要编写技能

每项技能都必须先有记录在案的证据，证明 Claude 在没有该技能时会失败。这可以验证你解决的是实际问题。没有失败测试，不得开始实现；没有证据，不得接受完成声明。关于对抗性验证和覆盖率门槛的详细执行模式，请参阅 imbue:proof-of-work。

技能类型

我们将技能分为三类：用于特定方法的技巧技能、用于重复出现的解决方案的模式技能，以及用于快速查阅和核对清单的参考技能。这有助于将干预措施整理成最适合任务的形式。

快速入门

技能分析

```bash

分析技能复杂度

python scripts/skill_analyzer.py

估算令牌数

python scripts/token_estimator.py ```

验证

```bash

验证技能结构

python scripts/abstract_validator.py --check ```

验证：继续之前，先运行分析并查看令牌估算结果。

描述优化

技能描述必须针对语义搜索和显式触发展开优化。遵循公式 [它的作用] + [何时使用] + [关键触发条件]。使用第三人称语态（例如“指导……” “提供……”），并加入具体明确的使用场景。避免营销用语或“帮助编写代码”之类含糊的表述。

技能描述字符预算（Claude Code 2.1.32+）

技能描述的字符预算现在会按上下文窗口大小动态调整，为可用上下文的 2%。这意味着：

上下文窗口	描述预算
200K（Sonnet/Haiku）	约 4,000 个字符
1M（Opus 4.6 GA）	约 20,000 个字符

此前受限的技能在更大的上下文窗口中可以使用更多描述性文字。不过，无论如何都应保持描述简洁：越长并不代表越好。此调整主要用于防止触发条件确实复杂的技能遭到截断，并非鼓励添加冗长内容。

插件名称自动显示（Claude Code 2.1.33+）

现在，/skills 菜单会自动在技能描述旁显示插件名称。不要在技能描述中重复插件名称：这样既多余，又会浪费字符预算。描述应聚焦于技能的作用及其适用时机。

技能的 TDD 循环

RED 阶段：记录基线失败

通过实证证明确实需要进行干预。至少创建三个兼具时间压力和模糊性的压力场景。在全新实例中、未启用该技能的情况下运行这些场景，并记录具体的失败表现，例如跳过错误处理或缺少验证。

GREEN 阶段：最小化技能实现

创建能够解决已记录失败的最小干预。编写包含必需 frontmatter 和内容的 SKILL.md，直接针对基线失败进行应对。加入一个正确行为示例，并验证相同的压力场景现在有可衡量的改善。

REFACTOR 阶段：强化触发条件

消除 Claude 为要求找借口的空间。启用技能后运行压力场景，找出常见的合理化说法，例如声称任务“太简单”，不值得走完整流程。添加明确的应对措施，例如例外表和危险信号清单，直到不再出现合理化说法。

判断技能是否适用

技能必须明确应对 Claude 试图绕过要求的模式。常见借口包括声称任务“太简单”，或认为采取“重精神、轻字面”的做法就足够。技能应加入危险信号清单，用于自我检查，例如“如果你认为：这个任务太简单，不值得走完整流程，就停下来。”如有必要设置例外，应明确记录，以防未经授权地走捷径。

模块参考

如需详细的实现指南：

核心编写周期：

• TDD 方法：参阅 modules/tdd-methodology.md，了解 RED-GREEN-REFACTOR 周期的详情
• 指令强度：参阅 modules/persuasion-principles.md，了解施加多大约束力度，以及哪些情况需要设为不可违反的规则
• 描述编写：参阅 modules/description-writing.md，了解如何优化发现效果
• 渐进式披露：参阅 modules/progressive-disclosure.md，了解文件结构模式
• 技能选择：参阅 ../../shared-modules/skill-selection-judgment.md，了解如何判断技能是否适用
• Graphviz 约定：参阅 modules/graphviz-conventions.md，了解流程图标准

处理具体技能（实现或调试时加载）：

• 示例详解：参阅 modules/examples.md，了解本仓库中编写完善的技能示例及其讲解
• 高级模式：参阅 modules/advanced-patterns.md，了解技能间协作、条件行为，以及如何在不同激活场景中扩展
• 身份验证：参阅 modules/authentication.md，了解调用 gh、glab、MCP 服务或其他需身份验证工具的技能
• 错误处理：参阅 modules/error-handling.md，了解工具缺失、超时、子 Agent 结果不完整以及权限被拒绝等情况
• 故障排查：参阅 modules/troubleshooting.md，了解如何诊断行为不符合测试语料预期的技能

验证和部署（发布时加载）：

• 验证：参阅 modules/validation.md，了解合并前的 frontmatter 解析、引用解析和结构检查
• 使用子 Agent 进行测试：参阅 modules/testing-with-subagents.md，了解如何在全新的子 Agent 中运行 Iron Law 测试（更全面的压力测试方法见 abstract:subagent-testing）
• 部署清单：参阅 modules/deployment-checklist.md，了解提升技能前的最终验证

部署与质量关卡

部署前，确认 RED、GREEN 和 REFACTOR 阶段均已完成并记录。frontmatter 必须有效，描述必须经过优化，行数不得超过 500 行。确保所有模块引用均有效，并至少包含一个具体示例。

受众匹配

SKILL.md hub 是一份面向 practitioner 的文档：读者了解该领域，并希望了解本仓库对它的诠释。面向这样的读者撰写 hub；任何只有技能维护者才需要了解的内容，都放入 modules/，并在 frontmatter 的 modules: 中列出，这样 progressive_loading 就不会占用 hub 的令牌预算。500 行上限同样会迫使你做出这种划分，只不过这里依据的是读者，而不是行数。

如果技能的读者不是 practitioner，请在技能的开篇首行说明；如果作者尚未决定，先询问，不要猜测。层级表、苏格拉底式问题集和提取流程详见 scribe:slop-detector 模块 audience-targeting.md。

Scribe 验证

所有 Markdown 文件都必须通过 Scribe 验证。其中包括 slop 扫描，确保得分低于 2.5；以及文档验证，确认所有文件路径和命令示例都有效。为确保可读性，项目符号内容与散文的比例必须低于 60%。使用 Skill(scribe:slop-detector) 和 Agent(scribe:doc-verifier) 执行这些检查。

集成与最佳实践

单个技能使用 skill-authoring 创建，而较大型结构的架构由 modular-skills 负责。skills-eval 提供持续的质量评估。避免根据理论行为编写技能这一常见陷阱；始终以有据可查的失败案例指导开发。使用渐进式披露，避免文件变成臃肿的整体，并确保每项干预都聚焦且节省令牌。

配套技能

• Skill(superpowers:writing-skills)：这是上游 superpowers 对编写 Claude Code 技能的做法。将其作为补充参考，与本指南的 TDD 周期一起用于了解技能结构和写作技巧。

技能目录变量（2.1.69+）

技能可以在 SKILL.md 内容中使用 ${CLAUDE_SKILL_DIR} 引用自身目录。此变量会解析为包含 SKILL.md 文件的目录的绝对路径。用它引用同级文件、数据资源或模块路径，无需硬编码绝对路径：

See `${CLAUDE_SKILL_DIR}/modules/advanced-patterns.md`
for detailed patterns.

Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/check.py`

这对于随附脚本或数据文件、且需要可移植路径引用的技能尤其有用，无论插件安装在哪里，这些引用都能正常工作。

描述字段冒号修复（2.1.69+）

描述中包含冒号的技能（例如 description: "Triggers include: X, Y, Z"）过去无法从 SKILL.md frontmatter 加载。此问题已在 2.1.69 修复。现在，没有 description: 字段的技能也会出现在可用技能列表中（此前它们会被静默排除）。

故障排除

常见问题

技能未加载 检查 YAML frontmatter 语法和必填字段。 从 2.1.69 开始，没有 description: 字段的技能仍会显示在技能列表中，但描述中包含冒号时，必须在 YAML frontmatter 中加引号。

超出令牌限制 使用渐进式披露——将详细内容移至模块中

找不到模块 确认 SKILL.md 中的模块路径正确

退出标准

• RED 阶段已记录至少三个压力场景，展示 Claude 在没有该技能时会失败；并且在开始实施前，已准确记录失败描述。
• GREEN 阶段生成的 SKILL.md 包含有效的 YAML frontmatter（带引号的 description、必填的 name 字段），且能在 Claude Code 中无错误加载。
• REFACTOR 阶段至少记录一种发现的合理化模式，并在技能中加入明确的反制措施（例外表、危险信号清单或禁止使用的借口清单）。
• python scripts/abstract_validator.py --check 退出状态为 0，且 SKILL.md 少于 500 行。
• hub 面向一个明确声明的读者层级；面向其他层级的材料放在 modules/ 中，并在 frontmatter 中列出。