skill-development

Claude Code 插件的技能开发

概述

技能是模块化的知识包，可通过专业工作流、领域知识和捆绑资源扩展 Claude 的能力。它们能将 Claude 从通用 Agent 转变为专业专家。

技能采用渐进式披露——一种三级加载系统，可高效管理上下文：

1. 元数据（名称 + 描述）——始终位于上下文中（约 100 个单词）
2. SKILL.md 正文——技能触发时加载（约 1,500-2,000 个单词）
3. 捆绑资源——Claude 按需加载（不限量）

技能结构

skill-name/
├── SKILL.md              # Required: Core instructions
├── references/           # Optional: Detailed documentation
│   ├── patterns.md       #   Loaded when Claude needs detail
│   └── advanced.md
├── examples/             # Optional: Working code examples
│   └── example.sh        #   Users can copy and adapt
├── scripts/              # Optional: Executable utilities
│   └── validate.sh       #   Token-efficient, deterministic
└── assets/               # Optional: Output resources
    └── template.html     #   Used in output, not loaded into context

只创建实际需要的目录。 最精简的技能只需一个 SKILL.md。

SKILL.md 格式

Frontmatter（必需）

每个新技能都必须遵循以下规范格式。偏离此格式是导致技能无法触发的首要原因。

---
name: skill-name                                  # REQUIRED: kebab-case, matches directory name
description: One-sentence summary of what the skill covers. PROACTIVELY activate for: (1) concrete named trigger, (2) concrete named trigger, ..., (N) concrete named trigger. Provides: comma-separated capability nouns (concrete, not abstract).
---

或者，如果描述是多行的（仅在描述非常长时才需要——实际可行时优先使用单行）：

---
name: skill-name
description: |
  One-sentence summary. PROACTIVELY activate for: (1) trigger, (2) trigger, ..., (N) trigger. Provides: capability list.
---

Frontmatter 硬性规则

1. 必须包含 name:，并且必须与所在目录的名称完全一致（skills/skill-name/SKILL.md → name: skill-name）。
2. 必须包含 description:，并且必须同时包含 PROACTIVELY activate for: (1)... (N)... 枚举和 Provides: ... 能力列表。
3. 完全没有 frontmatter 的 SKILL.md 属于损坏文件。 它永远不会触发，也不会出现在技能发现中，应视为 P0 级错误。如果打开 SKILL.md 后发现第一行不是 ---，应先修复 frontmatter，再进行其他操作。
4. 列出具体、明确命名的触发条件——不要写抽象能力。 “PROACTIVELY activate for: (1) creating Azure Functions, (2) binding config” 是好的写法。“Use this skill when working with Azure” 则不合格。
5. 描述何时使用，而不是它能做什么。 描述会驱动路由，因此应从用户的角度写成触发条件列表。在结尾的 Provides: ... 中概述能力。
6. 描述应保持为 YAML 安全的单行文本。 如果使用 | 块标量，不要在行中间嵌入未转义的冒号或其他可能混淆 YAML 的字符。
7. 描述目标长度为 400-1000 个字符；硬性上限为 1024 个字符（Claude Code API 规范）。 Claude 当前的列表上限为每个条目 1536 个字符（在 v2.1.105 中从 250 提高），所有已安装技能的总预算约为模型上下文窗口的 1%。将触发关键词放在前面。如果确实需要的触发条件超过约 1000 个字符能容纳的数量，优先拆分为两个技能，而不是写成臃肿的描述。
8. 不要将跨领域的通用说明（Windows 路径、文档政策）写进 YAML 描述。 应将其放入 Markdown 正文。

规范的“良好”描述

description: Expert guide to Terraform AzureRM provider for Azure infrastructure. PROACTIVELY activate for: (1) authoring AzureRM resource blocks, (2) state management (remote backends, state locking), (3) module design and composition, (4) variable and output patterns, (5) provider version pinning, (6) debugging plan/apply errors, (7) importing existing Azure resources, (8) CI/CD for Terraform (Azure DevOps, GitHub Actions). Provides: AzureRM provider patterns, state backend templates, module scaffolding, debugging playbook, and import recipes.

错误的描述（以下每种写法都会导致路由不可靠）

# BROKEN: no frontmatter at all
# (file starts with `# Skill Title` - will not appear in discovery)

# BROKEN: wrong shape, no enumeration
description: Use this skill when working with Terraform.

# BROKEN: abstract capability, no triggers
description: Provides Terraform expertise and guidance.

# BROKEN: WHAT-it-does instead of WHEN-to-use
description: This skill contains Terraform AzureRM provider documentation.

# BROKEN: second person (wrong voice)
description: You should load this skill when the user mentions Terraform.

# BROKEN: missing Provides list
description: PROACTIVELY activate for: (1) Terraform tasks. (No Provides section means the capability summary is lost.)

# BROKEN: cross-cutting Windows boilerplate inside YAML
description: |
  Terraform expert. MANDATORY: Always Use Backslashes on Windows for File Paths...
  (This is routing-match pollution. Move Windows rules to the body.)

正文——写作风格

整个技能正文都应使用祈使／不定式形式（以动词开头的指令）：

正确（祈使句）：

To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.
Start by reading the configuration file.

错误（第二人称）：

You should create a hook by defining the event type.
You need to configure the MCP server.
You can use the grep tool to search.

正文——结构

# Skill Title

## Overview
[Purpose and when to use - 2-3 sentences]

## Quick Reference
[Tables with key facts, common values, or patterns]

## Core Content
[Essential procedures and workflows - the main value]

## Additional Resources

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

### Example Files
- **`examples/example.sh`** - Working example

正文——篇幅指南

目标	单词数
理想	1,500-2,000
最大值	3,000（绝对硬性上限）

如果 SKILL.md 超过 2,000 个单词，请将详细内容移至 references/ 文件。

篇幅控制流程：

1. 编写 SKILL.md 后，统计单词数（不包括 frontmatter）。使用 wc -w，或按每行约 5 个单词估算。
2. 如果超过 2,000 个单词，请找出属于参考资料的部分（详细表格、详尽列表、特定服务器配置、故障排除矩阵），并将其提取到 references/。
3. 提取后如果仍超过 3,000 个单词，说明技能范围过广——拆分为两个技能，或将更多内容移至参考资料。
4. 不要仅仅因为某个部分最初写在 SKILL.md 中，就将它留在其中。 始终评估每个部分是否值得保留在核心文件中。

正文 - 避免重复内容

在单个 SKILL.md 中，绝不要重复相同的表格、列表或内容块。添加任何表格或参考内容块之前，请先搜索文件，确认其中是否已有类似内容。

在 SKILL.md 和 references/ 之间，信息只能有一个存放位置。如果 references/patterns.md 中有详细表格，SKILL.md 就只应包含简短摘要和指向该参考文件的链接，而不是复制表格。

“≥ 2 处逐字副本 = 提取”门槛（强制）

编写或修订任何 skill 时，在将段落、表格、检查清单或围栏代码块粘贴到 SKILL.md 或参考文件之前，先运行此检查：

# From the plugin root - adjust path to the candidate paragraph's first distinctive line:
grep -rn "FIRST_DISTINCTIVE_LINE_OF_THE_BLOCK" skills/ agents/ commands/ README.md

判定规则（必须无例外地遵守）：

grep 在以下位置找到该内容块	操作
0 个其他文件	可以安全添加。继续。
1 个其他文件（这将成为第 2 份副本）	停止。 提取到 skills/_shared/<topic>.md（跨 skill 内容）或 skills/<this-skill>/references/<topic>.md（单个 skill 的详细内容）。将两个引用位置都替换为一行链接。
2 个或更多其他文件	视为 P1 缺陷。立即提取，然后检查是否还有其他位置出现。

此规则适用于规范流程段落、检查清单、审计表格，以及任何表述为“这是 X 的唯一权威定义”的内容块。此规则不适用于简短的一行定义、frontmatter 示例或“在以下情况下使用此 skill……”之类的通用短语——这些内容太短，不值得提取。

**为什么“将切片视为独立内容”是明显的错误：**如果一次只修订一个文件，却不使用 grep 搜索整个插件目录树，相同的规范文本最终就会出现在两个文件中。解决方法很简单：每当准备提交一个超过约 3 行的内容块时，先运行 grep 搜索。

资源类型

references/ - 按需加载的文档

• 详细模式、高级技巧、API 文档、迁移指南
• 保持 SKILL.md 精简，同时确保信息易于查找
• 每个文件可以包含 2,000-5,000 个以上的单词
• 对于大型文件（>10k 个单词），在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息只能放在 SKILL.md 或 references/ 中，不能两者都有

examples/ - 用户可以复制的可运行代码

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

scripts/ - 可执行工具

• 验证工具、测试辅助工具、自动化脚本
• 节省 token（执行时无需加载到上下文中）
• 应可执行并附有文档

assets/ - 输出资源（不加载到上下文中）

• 模板、图片、图标、样板代码、字体
• 用于 Claude 生成的输出，而非供 Claude 阅读

Skill 创建流程与常见错误

六步流程（用例 -> 规划资源 -> 创建结构 -> 编写内容 -> 验证 -> 迭代）以及完整的常见错误表格位于 references/creation-process-and-mistakes.md。核心要点：

1. 确定具体用例和用户实际会说的触发短语。
2. 规划可复用资源：scripts/、references/、assets/、examples/。
3. 只创建所需目录。
4. 先准备资源，再编写精简的 SKILL.md（第三人称描述、正文使用祈使句，约 1,500-2,000 个单词）。
5. 验证 frontmatter、触发短语数量（5 个以上）、没有重复内容块、正文少于 3,000 个单词，且所有引用的文件均存在。
6. 根据真实任务的使用情况进行迭代——强化触发条件，将较长章节提取到 references/ 中。

常见错误要点：触发条件薄弱、缺少同义词、单个 SKILL.md 内有重复内容块、所有内容都塞进单个文件（8,000 个单词）的 skill、正文使用第二人称、描述超过 1024 个字符的上限。

自动发现

Claude Code 会自动发现技能：

1. 扫描 skills/ 目录，查找包含 SKILL.md 的子目录
2. 启动时加载元数据（名称和描述）
3. 根据描述匹配结果，在技能触发时加载 SKILL.md 正文
4. 在 Claude 判断有需要时加载参考资料和示例

无需配置——只需将 SKILL.md 放在正确的位置即可。