creating-skills

创建技能

遵循 Anthropic 官方最佳实践创建 Claude Code 技能的指南。

快速入门

# 1. Create skill directory
mkdir -p ~/.claude/skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
---

# <Skill title>

<Instructions for the skill workflow>
EOF

# 3. Add optional resources as needed
mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}

SKILL.md 结构

Frontmatter（--- 标记之间的 YAML）

字段	必填	描述
name	否	显示名称。默认为目录名称。使用小写字母和连字符，最多 64 个字符。
description	建议填写	描述内容、适用时机和功能。最多 1024 个字符。决定 Claude 何时启用该技能。
allowed-tools	否	技能处于启用状态时，Claude 无需请求许可即可使用的工具。
argument-hint	否	参数的自动补全提示。示例：[issue-number]
disable-model-invocation	否	设为 true 可阻止自动调用（只能手动使用 /name 调用）。
user-invocable	否	设为 false 可在 / 菜单中隐藏（仅作为后台知识）。
model	否	技能处于启用状态时使用的模型覆盖项。
context	否	设为 fork 可在隔离的子 Agent 上下文中运行。
agent	否	context: fork 时使用的子 Agent 类型。内置类型：Explore、Plan、general-purpose。
hooks	否	限定于此技能的生命周期钩子。

调用控制矩阵

配置	用户可以调用	Claude 可以调用
（默认）	是	是
disable-model-invocation: true	是	否
user-invocable: false	否	是

描述公式

<What it does>. Use when <trigger phrases>. <Key capabilities>.

加入动作动词（“创建”“处理”）、用户意图（“想要”“需要”）以及用户可能会提及的领域关键词。

目录结构

skill-name/
├── SKILL.md              # Required: instructions (keep under 500 lines)
├── scripts/              # Optional: executable code (deterministic, token-efficient)
├── references/           # Optional: docs loaded into context on demand
└── assets/               # Optional: files used in output, NOT loaded into context
                          #   (templates, images, fonts, boilerplate)

渐进式披露（3 级加载）

1. 元数据（名称 + 描述）——始终位于上下文中（每项技能约 100 个 token）
2. SKILL.md 正文——技能触发时加载（控制在 5k 词以内）
3. 捆绑资源——Claude 按需加载

在 SKILL.md 中引用支持文件，让 Claude 知道这些文件的存在。引用层级保持在一层以内。对于超过 100 行的文件，请添加目录。

脚本、参考资料与资源

类型	用途	是否加载到上下文中？
scripts/	确定性操作、复杂处理	否（通过 bash 执行）
references/	Claude 工作时阅读的文档	是，按需加载
assets/	用于输出的模板、图片、字体	否（复制或用于输出）

仅在脚本确实有价值时才创建：用于复杂的多步骤处理、重复代码生成或确保确定性。不要为单命令封装器创建脚本。

动态功能

上下文注入

在加载前将 shell 命令输出注入技能内容：

## Recent commits
!`git log --oneline -5 2>/dev/null`

技能加载时，输出会替换该指令。

字符串替换

向通过 /skill-name arg1 arg2 调用的技能传递参数：

变量	值
$ARGUMENTS	完整参数字符串
$ARGUMENTS[0]、$ARGUMENTS[1]	单个参数
$1、$2	$ARGUMENTS[N] 的简写形式

子 Agent 执行

使用 context: fork 在隔离的上下文中运行技能：

---
name: deep-research
description: Research a topic thoroughly.
context: fork
agent: Explore
---

自由度

根据任务的脆弱程度调整具体程度：

级别	适用场景	示例
高（文本指令）	存在多种有效方法，且取决于上下文	“分析代码并提出改进建议”
中（带参数的伪代码/脚本）	有首选模式，但允许一定变化	带可配置参数的脚本
低（特定脚本、少量参数）	操作脆弱、一致性至关重要	精确的 API 调用顺序

命名约定

• 使用小写字母，单词之间以连字符分隔，最多 64 个字符
• 命名风格：动名词（processing-pdfs）、名词短语（github-pr-creation）、带前缀的分组名称（github-pr-*）

重要规则

• 始终编写包含内容 + 触发时机 + 能力的描述
• 始终将 SKILL.md 控制在 500 行以内，接近上限时拆分到参考文件中
• 始终在 SKILL.md 中引用随附文件，以便 Claude 发现它们
• 绝不在 SKILL.md 和参考文件之间重复信息
• 绝不为单个命令创建包装脚本
• 绝不包含多余文件（README.md、CHANGELOG.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md）
• 绝不解释 Claude 已经了解的内容（标准库、常用工具、基本模式）

参考资料

• references/official_best_practices.md - 原则、反模式、质量检查清单、测试
• references/skill_examples.md - 展示新功能的具体技能示例