skill-development

Claude Code 插件的技能开发

本技能提供了为 Claude Code 插件创建高效技能的指导。

关于技能

技能是模块化、自包含的软件包，通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以把它们看作特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备流程知识的专业 Agent，而这些知识是任何模型都无法完全掌握的。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司特定的知识、架构和业务逻辑
4. 捆绑资源——用于复杂且重复任务的脚本、参考资料和资源

技能的组成

每项技能都包含一个必需的 SKILL.md 文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必需）

元数据质量： YAML 前置内容中的 name 和 description 决定 Claude 何时使用该技能。请具体说明技能的用途和适用时机。使用第三人称表述（例如，使用“This skill should be used when...”而非“Use this skill when...”）。

捆绑资源（可选）

脚本（scripts/）

用于需要确定性可靠性的任务，或经常需要重写的任务的可执行代码（Python/Bash 等）。

• 适用情形：需要反复重写相同代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 Token、结果确定，且可能无需加载到上下文中即可执行
• 注意：Claude 可能仍需读取脚本，以便进行修补或针对特定环境调整

参考资料（references/）

文档和参考材料，可按需加载到上下文中，为 Claude 的流程和思考提供参考。

• 适用情形：Claude 工作时需要参考文档
• 示例：财务架构的 references/finance.md、公司 NDA 模板的 references/mnda.md、公司政策的 references/policies.md、API 规范的 references/api_docs.md
• 用途：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，仅在 Claude 判断需要时加载
• 最佳实践：如果文件较大（>10k 词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或 references 文件中，而不是两边都有。除非信息确实是技能的核心内容，否则详细信息优先放在 references 文件中；这样既能让 SKILL.md 保持精简，也能让信息易于查找，而不会占用过多上下文窗口。SKILL.md 中仅保留必要的流程说明和工作流指导；将详细的参考材料、架构和示例移至 references 文件。

资源文件（assets/）

不打算加载到上下文中，而是供 Claude 在生成输出时使用的文件。

• 适用情形：技能需要在最终输出中使用文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板文件 assets/frontend-template/、字体 assets/font.ttf
• 用途：模板、图像、图标、样板代码、字体、可复制或修改的示例文档
• 优点：将输出资源与文档分开，使 Claude 无需将文件加载到上下文中即可使用

渐进式披露设计原则

技能采用三级加载系统，高效管理上下文：

1. 元数据（名称 + 描述） - 始终处于上下文中（约 100 个词）
2. SKILL.md 正文 - 技能触发时加载（少于 5k 个词）
3. 打包资源 - Claude 按需加载（无限*）

*之所以称为无限，是因为无需将脚本读入上下文窗口即可执行。

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，仅在有明确理由表明某些步骤不适用时才跳过。

步骤 1：通过具体示例了解技能

仅当已充分了解技能的使用模式时，才跳过此步骤。即使是处理现有技能，此步骤仍很有价值。

要创建有效的技能，请明确了解技能的具体使用示例。这些示例可以来自用户直接提供的示例，也可以由系统生成，并通过用户反馈进行验证。

例如，构建图像编辑器技能时，相关问题包括：

• “图像编辑器技能应该支持哪些功能？编辑、旋转，还有其他功能吗？”
• “能给出一些这个技能的使用示例吗？”
• “我能想到用户可能会提出‘去掉这张图片中的红眼’或‘旋转这张图片’之类的请求。你还能想到其他用法吗？”
• “用户说什么话时应该触发这个技能？”

为避免让用户应接不暇，请勿在一条消息中提出太多问题。先问最重要的问题，再根据需要继续提问，以提高效果。

当明确了解技能应支持的功能后，结束此步骤。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请逐一分析每个示例：

1. 思考如何从头开始完成该示例
2. 确定重复执行这些工作流时，有哪些脚本、参考资料和素材会有所帮助

示例：构建 pdf-editor 技能来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会很有帮助

示例：设计 frontend-webapp-builder 技能来处理“帮我构建一个待办事项应用”或“帮我构建一个追踪步数的仪表板”之类的请求时，分析表明：

1. 编写前端 Web 应用每次都需要相同的样板 HTML/React
2. 在技能中存放一个包含样板 HTML/React 项目文件的 assets/hello-world/ 模板会很有帮助

示例：构建 big-query 技能来处理“今天有多少用户登录过？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新查找表结构及其关系
2. 将记录表结构的 references/schema.md 文件存放在技能中会很有帮助

对于 Claude Code 插件： 构建 hooks 技能时，分析表明：

1. 开发者需要反复验证 hooks.json 并测试 hook 脚本
2. scripts/validate-hook-schema.sh 和 scripts/test-hook.sh 实用工具会很有帮助
3. references/patterns.md 可记录详细的 hook 模式，避免 SKILL.md 内容过于臃肿

为确定技能内容，请分析每个具体示例，并列出要包含的可复用资源：脚本、参考资料和素材。

步骤 3：创建技能结构

对于 Claude Code 插件，请创建以下技能目录结构：

mkdir -p plugin-name/skills/skill-name/{references,examples,scripts}
touch plugin-name/skills/skill-name/SKILL.md

注意： 不同于使用 init_skill.py 的通用 skill-creator，插件技能直接在插件的 skills/ 目录中创建，采用更简单的手动结构。

第 4 步：编辑 Skill

编辑（新创建或现有的）Skill 时，请记住，此 Skill 是为另一个 Claude 实例创建的。重点纳入对 Claude 有帮助且不显而易见的信息。考虑哪些流程知识、领域专属细节或可复用资源能帮助另一个 Claude 实例更有效地完成这些任务。

从可复用的 Skill 内容开始

开始实施时，先处理上面确定的可复用资源：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，在实现 brand-guidelines Skill 时，用户可能需要提供品牌素材或模板，以存放在 assets/ 中；也可能需要提供文档，以存放在 references/ 中。

另外，删除 Skill 不需要的示例文件和目录。仅创建实际需要的目录（references/、examples/、scripts/）。

更新 SKILL.md

写作风格： 整个 Skill 使用祈使式／不定式（以动词开头的指示语）撰写，而不要使用第二人称。采用客观、指导性的语言（例如，“要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样能让内容对 AI 来说保持一致、清晰。

描述（Frontmatter）： 使用第三人称格式，并包含具体触发短语：

---
name: Skill Name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", "specific phrase 3". Include exact phrases users would say that should trigger this skill. Be concrete and specific.
version: 0.1.0
---

良好描述示例：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", or mentions hook events (PreToolUse, PostToolUse, Stop).

不良描述示例：

description: Use this skill when working with hooks.  # Wrong person, vague
description: Load when user needs hook help.  # Not third person
description: Provides hook guidance.  # No trigger phrases

要完成 SKILL.md 正文，请回答以下问题：

1. Skill 的用途是什么？请用几句话说明。
2. 何时应使用此 Skill？（在 frontmatter 描述中加入具体触发短语）
3. 实际使用中，Claude 应如何使用此 Skill？请引用上面创建的所有可复用 Skill 内容，让 Claude 知道如何使用。

保持 SKILL.md 精简： 正文目标为 1,500–2,000 个单词。将详细内容移至 references/：

• 详细模式 → references/patterns.md
• 高级技巧 → references/advanced.md
• 迁移指南 → references/migration.md
• API 参考 → references/api-reference.md

在 SKILL.md 中引用资源：

## Additional Resources

### Reference Files

For detailed patterns and techniques, consult:
- **`references/patterns.md`** - Common patterns
- **`references/advanced.md`** - Advanced use cases

### Example Files

Working examples in `examples/`:
- **`example-script.sh`** - Working example

第 5 步：验证和测试

对于插件 Skill，验证方式不同于通用 Skill：

1. 检查结构：Skill 目录位于 plugin-name/skills/skill-name/
2. 验证 SKILL.md：包含带有 name 和 description 的 frontmatter
3. 检查触发短语：描述中包含具体的用户查询
4. 验证写作风格：正文使用祈使式／不定式，而非第二人称
5. 测试渐进式披露：SKILL.md 保持精简（约 1,500–2,000 个单词），详细内容放在 references/ 中
6. 检查参考文件：所有引用的文件均存在
7. 验证示例：示例完整且正确
8. 测试脚本：脚本可执行且运行正确

使用 skill-reviewer Agent：

Ask: "Review my skill and check if it follows best practices"

skill-reviewer Agent 将检查描述质量、内容组织和渐进式披露。

第 6 步：迭代

测试 Skill 后，用户可能会要求改进。通常这会在刚使用完 Skill 后发生，此时用户对其表现还有清晰的印象。

迭代工作流：

1. 在实际任务中使用 Skill
2. 留意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或随附资源
4. 实施更改并再次测试

常见改进：

• 强化描述中的触发短语
• 将 SKILL.md 中的长篇内容移至 references/
• 添加缺失的示例或脚本
• 澄清含糊的指示
• 添加边缘情况处理

插件专属注意事项

插件中的 Skill 位置

插件 Skill 位于插件的 skills/ 目录中：

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── references/
        ├── examples/
        └── scripts/

自动发现

Claude Code 会自动发现 Skill：

• 扫描 skills/ 目录
• 查找包含 SKILL.md 的子目录
• 始终加载 Skill 元数据（name + description）
• 在 Skill 触发时加载 SKILL.md 正文
• 按需加载 references/examples

无需打包

插件技能作为插件的一部分分发，而不是单独的 ZIP 文件。用户在安装插件时即可获得技能。

在插件中测试

通过在本地安装插件来测试技能：

# Test with --plugin-dir
cc --plugin-dir /path/to/plugin

# Ask questions that should trigger the skill
# Verify skill loads correctly

来自 Plugin-Dev 的示例

研究此插件中的技能，作为最佳实践的示例：

hook-development 技能：

• 出色的触发短语：“create a hook”、“add a PreToolUse hook”等。
• 精简的 SKILL.md（1,651 词）
• 3 个 references/ 文件用于详细内容
• 3 个 examples/ 展示可用的 hooks
• 3 个 scripts/ 实用工具

agent-development 技能：

• 强有力的触发词：“create an agent”、“agent frontmatter”等。
• 聚焦的 SKILL.md（1,438 词）
• References 包含来自 Claude Code 的 AI 生成提示词
• 完整的 Agent 示例

plugin-settings 技能：

• 具体的触发词：“plugin settings”、“.local.md files”、“YAML frontmatter”
• References 展示真实实现（multi-agent-swarm、ralph-loop）
• 可用的解析脚本

每个示例都展示了渐进式披露和强有力的触发。

渐进式披露实践

SKILL.md 中应包含什么

包含（技能触发时始终加载）：

• 核心概念和概述
• 必要的流程和工作流
• 快速参考表
• 指向 references/examples/scripts 的指引
• 最常见的用例

保持在 3,000 词以内，理想为 1,500-2,000 词

references/ 中应包含什么

移至 references/（按需加载）：

• 详细的模式和高级技巧
• 全面的 API 文档
• 迁移指南
• 边缘情况和故障排除
• 大量示例和演练

每个 reference 文件可以很大（2,000-5,000+ 词）

examples/ 中应包含什么

可用的代码示例：

• 完整、可运行的脚本
• 配置文件
• 模板文件
• 真实世界的使用示例

用户可以直接复制和改编这些内容

scripts/ 中应包含什么

实用脚本：

• 验证工具
• 测试辅助工具
• 解析实用工具
• 自动化脚本

应当可执行并有文档说明

写作风格要求

祈使/不定式形式

使用动词开头的指令编写，而非第二人称：

正确（祈使式）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.

错误（第二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You must validate settings before use.

描述中使用第三人称

Frontmatter 的 description 必须使用第三人称：

正确：

description: This skill should be used when the user asks to "create X", "configure Y"...

错误：

description: Use this skill when you want to create X...
description: Load this skill when user asks...

客观的指导性语言

关注要做什么，而不是谁应该做：

正确：

Parse the frontmatter using sed.
Extract fields with grep.
Validate values before use.

错误：

You can parse the frontmatter...
Claude should extract fields...
The user might validate values...

验证清单

在最终确定技能之前：

结构：

• SKILL.md 文件存在且具有有效的 YAML frontmatter
• Frontmatter 包含 name 和 description 字段
• Markdown 正文存在且内容充实
• 引用的文件确实存在

描述质量：

• 使用第三人称（“This skill should be used when...”）
• 包含用户会说的具体触发短语
• 列出具体场景（“create X”、“configure Y”）
• 不模糊或笼统

内容质量：

• SKILL.md 正文使用祈使/不定式形式
• 正文聚焦且精简（理想 1,500-2,000 词，最多 <5k）
• 详细内容移至 references/
• 示例完整且可用
• 脚本可执行并有文档说明

渐进式披露：

• 核心概念在 SKILL.md 中
• 详细文档在 references/ 中
• 可用代码在 examples/ 中
• 实用工具在 scripts/ 中
• SKILL.md 引用了这些资源

测试：

• 技能在预期的用户查询上触发
• 内容对预期任务有帮助
• 文件之间没有重复信息
• References 在需要时加载

应避免的常见错误

错误 1：触发描述薄弱

❌ 差：

description: Provides guidance for working with hooks.

为什么差： 模糊，没有具体的触发短语，不是第三人称

✅ 好：

description: This skill should be used when the user asks to "create a hook", "add a PreToolUse hook", "validate tool use", or mentions hook events. Provides comprehensive hooks API guidance.

为什么好： 第三人称，具体的短语，具体的场景

错误 2：SKILL.md 内容过多

❌ 错误：

skill-name/
└── SKILL.md  (8,000 words - everything in one file)

错误原因： 技能加载时会占用过多上下文，详细内容总是会被加载。

✅ 正确：

skill-name/
├── SKILL.md  (1,800 words - core essentials)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

正确原因： 渐进式披露，仅在需要时加载详细内容。

错误 3：使用第二人称写作

❌ 错误：

You should start by reading the configuration file.
You need to validate the input.
You can use the grep tool to search.

错误原因： 使用了第二人称，而不是祈使形式。

✅ 正确：

Start by reading the configuration file.
Validate the input before processing.
Use the grep tool to search for patterns.

正确原因： 使用祈使形式，指令直接明确。

错误 4：缺少资源引用

❌ 错误：

# SKILL.md

[Core content]

[No mention of references/ or examples/]

错误原因： Claude 不知道这些引用的存在。

✅ 正确：

# SKILL.md

[Core content]

## Additional Resources

### Reference Files
- **`references/patterns.md`** - Detailed patterns
- **`references/advanced.md`** - Advanced techniques

### Examples
- **`examples/script.sh`** - Working example

正确原因： Claude 知道在哪里查找更多信息。

快速参考

最精简的技能

skill-name/
└── SKILL.md

适用于：简单知识，无需复杂资源

标准技能（推荐）

skill-name/
├── SKILL.md
├── references/
│   └── detailed-guide.md
└── examples/
    └── working-example.sh

适用于：大多数带有详细文档的插件技能

完整技能

skill-name/
├── SKILL.md
├── references/
│   ├── patterns.md
│   └── advanced.md
├── examples/
│   ├── example1.sh
│   └── example2.json
└── scripts/
    └── validate.sh

适用于：包含验证工具的复杂领域

最佳实践总结

✅ 应做：

• 在描述中使用第三人称（“应在……时使用此技能”）
• 添加明确的触发短语（“创建 X”“配置 Y”）
• 保持 SKILL.md 精简（1,500–2,000 个词）
• 使用渐进式披露（将详细内容移至 references/）
• 使用祈使或不定式形式撰写
• 清楚地引用支持文件
• 提供可运行的示例
• 为常见操作创建实用脚本
• 参考 plugin-dev 的技能作为模板

❌ 不应做：

• 在任何地方使用第二人称
• 使用含糊的触发条件
• 将所有内容都放进 SKILL.md（超过 3,000 个词且没有 references/）
• 使用第二人称撰写（“你应该……”）
• 不引用资源
• 包含无法运行或不完整的示例
• 跳过验证

其他资源

研究以下技能

Plugin-dev 的技能展示了最佳实践：

• ../hook-development/ - 渐进式披露、实用工具
• ../agent-development/ - AI 辅助创建、引用
• ../mcp-integration/ - 全面的引用资料
• ../plugin-settings/ - 实际示例
• ../command-development/ - 清晰的关键概念
• ../plugin-structure/ - 良好的组织结构

参考文件

如需了解完整的 skill-creator 方法：

• references/skill-creator-original.md - skill-creator 的完整原始内容

实施工作流

为插件创建技能：

1. 了解用例：找出技能使用方式的具体示例
2. 规划资源：确定所需的脚本、引用资料和示例
3. 创建结构：mkdir -p skills/skill-name/{references,examples,scripts}
4. 编写 SKILL.md：
   • Frontmatter 中包含第三人称描述和触发短语
   • 正文保持精简（1,500–2,000 个词），并使用祈使形式
   • 引用支持文件
5. 添加资源：按需创建 references/、examples/、scripts/
6. 验证：检查描述、写作风格和组织结构
7. 测试：确认技能会在预期的触发条件下加载
8. 迭代：根据使用情况改进

重点关注明确的触发描述、渐进式披露和祈使式写作风格，以打造有效的技能，使其在需要时加载并提供有针对性的指导。