一、自定义Skill的设计原则
创建一个优秀的自定义Skill，首先需要遵循正确的设计原则。好的设计能让Skill易于使用、维护和扩展。以下是Skill设计的四大核心原则：
单一职责
一个Skill只做一件事，做好一件事。避免在一个Skill中混杂多个不相关的功能，保持逻辑清晰。
明确命名
/command 名称见名知意，用户看到命令名就能大致了解其功能，无需额外解释。
可参数化
通过 {{arg}} 和 {{name}} 等占位符实现灵活输入，让同一个Skill能处理不同的具体场景。
输出明确
定义清晰的输出格式和内容，让用户对Skill的执行结果有明确预期。
1.1 单一职责原则详解
一个Skill定义在CLAUDE.md中对应一个触发命令，它应该专注于完成一个特定的任务。例如，"代码审查Skill"只做代码审查，"文档生成Skill"只做文档生成。如果发现一个Skill中包含了多个不相关的prompt指令，说明需要拆分成多个独立的Skill。
最佳实践： 在编写Skill之前，先用一句话回答"这个Skill帮用户解决什么问题？"如果一句话说不清楚，说明职责划分不够清晰。
1.2 命令命名规范
Skill的触发命令使用斜杠开头（如 /review、/test、/doc-gen），建议遵循以下规范：
- 使用英文小写：
/code-review 而非 /CodeReview
- 用连字符分隔：
/doc-gen 而非 /docgen
- 避免过于通用：
/fix-bug 比 /fix 更明确
- 控制在2-4个单词：过长的命令不易记忆
1.3 参数化设计模式
Skill支持多种参数传递方式，合理利用可以实现高度灵活的命令：
- 位置参数：
/greet 张三 → Skill中通过 $1 引用"张三"
- 命名参数：
/send-report --to 张三 --title 周报 → 通过参数名引用
- 标准输入：管道传入内容，Skill中通过
{{INPUT}} 或 $STDIN 引用
- 环境变量：通过
$VAR_NAME 引用当前Shell环境变量
# Skill声明示例 - 支持多种参数模式的CLAUDE.md配置
- name: greet
description: 向指定用户发送问候消息
command: /greet
args:
- name: username
description: 接收问候的用户名称
required: true
- name: title
description: 用户头衔
required: false
prompt: |
向 {{username}} 发送问候消息。
{% if title %}称呼为 {{title}} {{username}}{% endif %}
问候语要热情友好，包含对用户的肯定和鼓励。
二、prompt模板编写技巧
Skill的核心是prompt模板，它决定了AI的行为和输出质量。编写高质量的prompt模板是Skill开发的关键技能。以下是经过实践验证的编写技巧：
2.1 清晰指令原则
在prompt的开头，用最简洁的语言告诉AI它需要做什么。避免绕弯子或过多的背景铺垫，直接进入主题。使用祈使句开头效果最好。
# 好的示例：指令清晰明确
你是一个代码审查助手。请审查以下代码变更，找出潜在的问题。
changes:
{{INPUT}}
请输出审查结果，包含：bug风险、性能问题、代码风格建议。
常见错误： 过多的背景铺垫会让AI混淆优先级。把最重要的指令放在 prompt 的最前面，辅助信息往后放。
2.2 结构化输出格式
使用Markdown、代码块、列表等格式化方式，让AI的输出整齐有序。结构化输出不仅美观，更重要的是便于用户快速定位信息。
- 使用
## 标题 分隔不同模块
- 使用
- 列表 罗列要点
- 使用
```代码块 展示代码或配置
- 使用
| 表格 | 展示对比数据
2.3 Few-shot示例
在prompt中提供1-3个输入输出示例，可以显著提高AI输出的准确性和一致性。示例应该覆盖典型场景和边界情况。
# Few-shot 示例模板
请根据用户描述生成Git commit message。
示例1：
输入：修复了用户登录时密码验证不通过的问题
输出：fix: 修复用户登录密码验证失败问题
示例2：
输入：新增用户头像上传功能和个人信息编辑页面
输出：feat: 新增用户头像上传及个人信息编辑
示例3：
输入：重构了数据库查询模块，把原始SQL改成了ORM
输出：refactor: 将数据库查询从原始SQL迁移至ORM
现在请为以下描述生成commit message：
2.4 约束条件和边界处理
明确的约束条件能防止AI输出偏离预期。常见的约束包括：
- 长度限制：回复控制在200字以内 / 最多列出5条建议
- 格式限制：必须使用JSON格式输出 / 每行一个条目
- 风格限制：使用专业严谨的语气 / 使用口语化表达
- 边界处理：如果输入不完整，请提示缺少的信息 / 如果遇到无法处理的情况，请说明原因
技巧： 除了告诉AI"要做什么"，明确告诉AI"不要做什么"同样重要。例如："不要编造不存在的信息"、"不要使用过于技术性的术语"、"如果信息不足，请直接询问而不是猜测"。
三、多步骤复合Skill
当任务需要多个步骤协同完成时，可以创建复合Skill。复合Skill将复杂任务拆解为多个子步骤，逐步执行，最终输出完整结果。
3.1 步骤编排模式
复合Skill的prompt应该清晰地定义每个步骤及其顺序。步骤之间可以通过变量传递中间结果，形成完整的处理流水线。
# 多步骤复合Skill示例 - /create-component
你是一个组件创建助手。请按以下步骤为用户创建前端组件：
步骤一：需求分析
- 解析用户输入的组件需求
- 确定组件的props接口定义
- 确定组件的状态管理和生命周期
步骤二：代码生成
- 生成组件的TypeScript代码
- 生成组件的样式文件（CSS Modules）
- 生成组件的单元测试文件
步骤三：质量检查
- 检查生成的代码是否符合项目规范
- 检查是否有遗漏的边界情况
- 生成使用示例代码
用户需求：
{{INPUT}}
请按步骤依次执行，每完成一步输出该步骤的结果。
3.2 使用 {{INPUT}} 接收多行输入
当需要用户提供大量上下文信息时，使用 {{INPUT}} 占位符可以接收多行文本输入。这在创建文档生成、代码分析等需要大量输入的Skill时非常有用。
# 使用 {{INPUT}} 接收多行输入的Skill配置
- name: analyze-code
description: 分析代码库并提供改进建议
command: /analyze
prompt: |
分析以下代码并提供重构建议：
```代码
{{INPUT}}
```
请分析：
1. 代码中存在的设计问题
2. 性能瓶颈
3. 可读性改进建议
4. 推荐的修改方案
3.3 步骤间中间结果传递
对于特别复杂的任务，可以设计为每个步骤的输出作为下一步的输入。这种方式类似于函数式编程中的管道（pipe）模式。
复合Skill设计要点： 每个步骤的输出应该是结构化的，便于下一步解析；步骤之间尽量减少依赖；每个步骤都要有明确的完成标准；为每个步骤设置备选方案或错误处理逻辑。
3.4 错误处理和备选方案
健壮的Skill应该考虑到各种异常情况。在prompt中明确说明当遇到问题时的处理方式：
- 输入验证：检查输入是否符合预期格式，不符合时给出提示
- 缺失信息：当缺少必要信息时，主动询问而不是猜测
- 环境检查：执行前检查所需工具/文件是否存在
- 降级处理：当无法完成全部任务时，至少完成能做的部分
设计原则： 一个好的Skill应该"优雅地失败"（fail gracefully）——即使不能完成全部任务，也要给用户有价值的中间结果或明确的错误信息。
四、Skill测试和调试
创建完Skill后，测试和调试是确保其正常工作的关键环节。以下是一套完整的测试调试流程：
4.1 基本功能测试
修改CLAUDE.md后，在Claude Code中直接触发命令进行测试。验证以下方面：
# 测试检查清单
[ ] Skill命令是否被正确识别（输入 / 后能否自动补全）
[ ] 无参数时是否给出友好提示
[ ] 参数传递是否正确解析
[ ] 输出格式是否符合预期
[ ] 边界输入（空值/超长文本/特殊字符）是否正常处理
4.2 参数传递调试
参数传递是Skill调试中最容易出问题的环节。常见的问题包括：
- 参数名拼写错误：模板中的
{{name}} 与参数定义中的名称不一致
- 可选参数未处理：当可选参数未提供时模板中仍然引用了它
- 特殊字符转义：参数值中包含引号、反斜杠等特殊字符时处理不当
- 多行输入截断：使用
{{INPUT}} 时未考虑换行符的处理
调试技巧： 如果Skill没有按预期工作，首先检查CLAUDE.md中Skill定义的YAML格式是否正确（缩进是否一致、冒号后是否有空格）。YAML格式错误是Skill失效的最常见原因。
4.3 prompt模板格式调试
prompt模板中的格式问题可能导致AI理解偏差或输出异常。以下是最常见的格式问题：
- 缩进问题：YAML中使用缩进定义层级，prompt模板的缩进会被视为内容的一部分
- 特殊字符：模板中的
|、>、& 字符在YAML中有特殊含义，需要用引号包裹
- 空白行：多余的空白行可能会被保留并影响AI输出
- 条件逻辑：使用
{% if %} 等模板语法时，确保语法正确闭合
最佳实践： 在CLAUDE.md中使用 |（管道符）定义多行prompt时，保持每行的缩进一致。使用 |-（带减号的管道符）可以自动去掉末尾的换行符，避免多余空白行。
4.4 完整测试流程示例
# 测试流程示例
1. 编写Skill并保存CLAUDE.md
2. 在Claude Code中输入 /skill-name 触发
3. 不传参数检查提示信息是否友好
4. 传入正常参数检查输出质量
5. 传入边界值（超长/特殊字符）检查鲁棒性
6. 连续多次调用检查一致性
7. 修改prompt后重新测试对比效果差异
# 快速迭代技巧
- 先写最小可用版本，测试通过后再丰富prompt
- 每次只改一处，方便定位问题
- 保留测试记录，回归测试时对比
核心要点总结： 开发自定义Skill的核心流程可以概括为"四步法"：设计（明确职责和参数）→ 编写（构建prompt模板）→ 测试（验证功能和边界）→ 迭代（根据反馈优化）。掌握好这些基础技能后，可以进一步探索MCP工具集成、多Skill协同等高级用法。