writing-skills

Writing Skills - Claude 技能创建指南

技能概述

Writing Skills 将测试驱动开发（TDD）应用于技能文档编写，通过 RED-GREEN-REFACTOR 循环确保技能质量，帮助开发者创建可被发现、可被 Claude 代理有效使用的高质量技能。

适用场景

1. 创建新技能

当你掌握了一个可复用的技术模式、工具使用方法或问题解决思路，希望将其转化为技能供未来的 Claude 实例使用时。Writing Skills 提供完整的创建流程，从命名规则到目录结构，从内容组织到测试验证。

2. 编辑现有技能

当你需要改进已有技能的内容、修复漏洞或补充缺失的使用场景时。该技能强调任何编辑都必须先通过测试验证，确保修改真正解决问题而不引入新的问题。

3. 验证技能部署效果

在将技能部署到生产环境前，通过压力测试验证技能是否能被 Claude 正确理解和执行。Writing Skills 提供多种测试方法，针对不同类型的技能（纪律型、技术型、模式型、参考型）提供相应的验证策略。

核心功能

1. TDD 驱动的技能开发流程

将传统的测试驱动开发映射到文档编写领域：先运行压力测试观察代理在无技能时的违规行为（RED），编写最小化技能解决特定问题（GREEN），通过迭代测试修补漏洞（REFACTOR）。这确保每个技能都有明确的验证标准，避免"看起来清楚"但实际无法使用的文档。

2. Claude 搜索优化（CSO）指导

提供详细的 SEO 优化策略，让技能能被 Claude 代理发现和正确使用。包括：描述字段只描述触发条件而不总结工作流程、关键词覆盖错误信息和症状、使用动词优先的命名规范、控制 token 消耗的写作技巧。这些优化直接影响技能在实际对话中的加载和应用效果。

3. 技能类型分类与测试方法

将技能分为四类并提供对应的测试策略：纪律型技能通过学术问题和压力场景测试规则遵守情况；技术型技能通过应用场景和变体测试技术掌握程度；模式型技能通过识别场景测试思维模型应用；参考型技能通过检索场景测试信息查找准确性。每种类型都有明确的成功标准。

常见问题

什么是技能？技能和普通文档有什么区别？

技能是经过验证的可复用技术、模式或工具的参考指南，用于帮助未来的 Claude 实例找到并应用有效方法。技能关注的是通用性强、跨项目可复用的内容，而不是一次性解决方案。普通文档可能是叙事性的问题解决记录，而技能必须经过测试验证，确保代理能够正确理解和执行。

为什么创建技能必须先写测试？

这是 TDD 的核心理念在文档领域的应用。如果不先观察代理在无技能时的行为，你无法确定技能是否真正解决了问题。测试揭示了代理会使用哪些合理化借口来违反规则，哪些压力会导致错误决策，从而让技能编写有明确的目标。先写技能再测试往往会产生"看起来清楚"但实际无法被代理正确理解的文档。

如何让 Claude 发现并使用我的技能？

关键在于优化描述字段（description）。描述应该只描述触发条件和使用场景，而不总结技能的工作流程。如果描述包含了"代码审查"这样的流程总结，Claude 可能只执行一次审查就停止，即使技能正文明确要求多次审查。此外，还要在技能中包含错误信息、症状描述、同义词和实际工具名称，这些都是 Claude 搜索时会匹配的关键词。

技能有哪些类型？如何选择？

技能分为四类：技术型（有步骤的具体方法，如条件等待）、模式型（思维模型，如扁平化设计）、参考型（API 文档、语法指南）、纪律型（强制规则，如 TDD）。选择类型取决于你要记录的内容性质：可执行的步骤选技术型，思维方式选模式型，查询资料选参考型，必须遵守的规则选纪律型。

SKILL.md 应该包含哪些内容？

必须包含 YAML frontmatter（只有 name 和 description 字段）、概述（核心原理）、何时使用（适用场景和触发条件）、核心模式（前后的代码对比或说明）、快速参考（常见操作表格或列表）、实现细节（代码示例或文件链接）、常见错误、真实影响（可选）。内容要简洁，getting-started 技能控制在 150 词以内，常用技能 200 词以内，其他技能 500 词以内。