Skill 开发规范与最佳实践
引言
在 Claude Code 生态系统中，Skill 是扩展代理能力的重要组件。一个设计良好的 Skill 可以被其他代理调用，实现能力的复用和组合。然而，在实际开发过程中，我们发现了一个关键问题：Skill 的 description 字段应该如何编写？本文基于 CSO（Claude Search Optimization）规范，深入探讨 Skill 描述的编写原则。
描述字段的核心原则
描述应该描述触发条件，而非工作流程
Skill 的 description 字段是 Claude 理解何时应该调用该 Skill 的关键依据。经过多次测试，我们发现一个重要的规律：description 应该只描述触发条件，而不应该总结工作流程。
原因在于，当 description 包含工作流程总结时，Claude 会倾向于直接遵循描述中的简化流程，而不是阅读完整的 Skill 内容。这可能导致关键实现细节被忽略。
错误示例
{ "name": "planner", "description": "Use when executing plans - dispatches subagent per task with code review between tasks"}这个描述的问题在于，它总结了 planner 的工作流程（dispatch subagent、code review 等），这会引导 Claude 直接遵循这个流程，而不是阅读 planner 的完整技能定义。
正确示例
{ "name": "planner", "description": "Use when executing implementation plans with independent tasks"}这个描述只说明了触发条件（执行具有独立任务的实现计划），而没有透露任何实现细节。Claude 会因此主动阅读完整的 Skill 内容，从而获得准确的执行逻辑。
Skill 的结构
一个完整的 Skill 通常包含以下字段：
{ "name": "skill-name", "description": "Trigger condition only - what situations to use this skill in", "args": { "arg1": "Description of first argument", "arg2": "Description of second argument" }}关键字段说明：
- name: Skill 的名称，用于调用时的标识符
- description: 触发条件描述，应简洁明了，只说明何时使用
- args: 技能执行所需的参数定义
Skill 的发布与分发
个人 Skill 存储位置
个人开发的 Skill 存放在 ~/.claude/skills/ 目录下。这个位置允许用户创建私有技能，满足个人工作流的定制需求。
社区贡献
如果你希望将 Skill 贡献给社区，需要通过 Pull Request 的方式提交。社区 Skill 采用 MIT License，这意味着任何人都可以自由使用、修改和分发。
在提交 PR 之前，请确保：
- Skill 的 description 符合 CSO 规范
- 代码遵循现有的编码风格
- 包含必要的文档和使用示例
实践建议
1. 保持描述简洁
description 字段应该尽可能简短。一个好的经验法则是，描述不应该超过一句话。如果发现描述变得复杂，考虑将其拆分为多个 Skill。
2. 避免实现细节
描述中不应该包含：
- 具体的执行步骤
- 中间过程的说明
- 实现使用的技术栈
- 子代理的调度方式
3. 专注于触发场景
思考这个问题：当用户处于什么情况时，应该调用这个 Skill？将答案浓缩为一句话，就是好的 description。
4. 测试验证
编写完成后，进行实际测试：
- 观察 Claude 是否会阅读完整的 Skill 内容
- 验证执行结果是否符合预期
- 如果 Claude 跳过了 Skill 内容阅读，说明 description 可能过于详细
常见错误与修正
过度描述
错误：
"description": "Analyzes code using multi-pass review - first pass for structure, second for patterns, third for security issues"正确：
"description": "Use when performing comprehensive code analysis"包含工作流程
错误：
"description": "Uses tdd-guide agent first, then dispatches code-reviewer after implementation"正确：
"description": "Use for test-driven development workflow"总结
Skill 描述的编写看似简单，实则对 Skill 的实际效果有着重要影响。遵循 CSO 规范，专注于触发条件而非实现细节，可以确保 Claude 正确理解和使用 Skill。希望本文的规范和示例能够帮助开发者创建更高质量的 Skill。