create-agent-skills

创建技能与命令

本技能将教你如何按照 code.claude.com/docs/en/skills 中的官方规范创建有效的 Claude Code 技能。

命令与技能现在是同一回事

自定义斜杠命令已并入技能。.claude/commands/review.md 文件和 .claude/skills/review/SKILL.md 技能都会创建 /review，且工作方式相同。现有 .claude/commands/ 文件仍可继续使用。技能还提供可选功能：用于存放支持文件的目录、用于控制调用方式的 frontmatter，以及自动加载上下文。

如果技能和命令同名，则优先使用技能。

何时创建哪种

在以下情况使用命令文件（commands/name.md）：

• 简单的单文件工作流
• 不需要支持文件
• 面向任务的操作（部署、提交、分类）

在以下情况使用技能目录（skills/name/SKILL.md）：

• 需要支持性的参考文件、脚本或模板
• Claude 应自动加载的背景知识
• 复杂到适合渐进式披露

两者使用相同的 YAML frontmatter 和 Markdown 正文格式。

标准 Markdown 格式

使用 YAML frontmatter + Markdown 正文，并采用标准 Markdown 标题。保持简洁直接。

---
name: my-skill-name
description: What it does and when to use it
---

# My Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...

Frontmatter 参考

所有字段均为可选。仅建议填写 description。

字段	必填	说明
name	否	显示名称。使用小写字母、数字和连字符（最多 64 个字符）。默认为目录名称。
description	建议填写	说明其功能以及何时使用。Claude 会用它进行自动发现。最多 1024 个字符。
argument-hint	否	自动补全时显示的提示。例如：[issue-number]
disable-model-invocation	否	设为 true 可阻止 Claude 自动加载。适用于 /deploy、/commit 等手动工作流。默认值：false。
user-invocable	否	设为 false 可从 / 菜单中隐藏。适用于背景知识。默认值：true。
allowed-tools	否	Claude 无需权限提示即可使用的工具。例如：Read, Bash(git *)
model	否	要使用的模型。可选值：haiku、sonnet、opus。
context	否	设为 fork 可在隔离的子 Agent 上下文中运行。
agent	否	context: fork 时使用的子 Agent 类型。可选值：Explore、Plan、general-purpose 或自定义 Agent 名称。

调用控制

Frontmatter	用户能否调用	Claude 能否调用	加载时机
（默认）	是	是	描述始终在上下文中，调用时加载完整内容
disable-model-invocation: true	是	否	描述不在上下文中，仅在用户调用时加载
user-invocable: false	否	是	描述始终在上下文中，相关时加载

对具有副作用的工作流使用 disable-model-invocation: true：/deploy、/commit、/triage-prs、/send-slack-message。你不会希望 Claude 因为代码看起来已准备就绪，就自行决定部署。

对不属于有意义用户操作的背景知识使用 user-invocable: false：编码规范、领域背景、旧系统文档。

动态功能

参数

使用 $ARGUMENTS 占位符接收用户输入。如果内容中未包含该占位符，参数会自动追加。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

访问单个参数：$ARGUMENTS[0] 或简写 $0、$1、$2。

动态上下文注入

技能支持动态上下文注入：在用反引号括起来的 shell 命令前加一个感叹号，预处理器便会在加载时执行该命令，并用标准输出替换这条指令。在要执行的命令的起始反引号前立即写入感叹号（例如，要注入当前 git 分支，请写入感叹号，后面跟着用反引号括起来的 git branch --show-current）。

**重要：**预处理器会将整个 SKILL.md 作为纯文本扫描，不会解析 Markdown。围栏代码块或行内代码片段中的指令也会执行。如果某项技能通过字面示例介绍这种语法，预处理器仍会尝试运行这些示例，导致加载失败。要安全地介绍此功能，请像这里一样用文字描述，或将示例放在参考文件中。Claude 会按需加载参考文件，不会对其进行预处理。

如需查看技能中动态上下文注入的具体示例，请参阅 official-spec.md §“动态上下文注入”。

在子 Agent 中运行

添加 context: fork 可在隔离环境中运行。技能内容会成为子 Agent 的提示词。子 Agent 不会获得对话历史。

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

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

渐进式披露

将 SKILL.md 控制在 500 行以内。将详细内容拆分到参考文件中：

my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

从 SKILL.md 添加链接：For API details, see [reference.md](reference.md).

参考文件与 SKILL.md 的引用层级应保持一层。避免嵌套引用链。

有效的描述

描述有助于发现技能。应同时说明技能的作用和适用时机。

良好示例：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

不佳示例：

description: Helps with documents

你想做什么？

1. 创建新技能 - 从头开始构建
2. 创建新命令 - 构建斜杠命令
3. 审查现有技能 - 检查是否符合最佳实践
4. 添加组件 - 添加工作流／参考资料／示例
5. 获取指导 - 了解技能设计

创建新技能或命令

第 1 步：选择类型

思考：这是手动工作流（部署、提交、分类处理），还是背景知识（约定、模式）？

• 手动工作流 → 使用 disable-model-invocation: true 的命令
• 背景知识 → 不使用 disable-model-invocation 的技能
• 包含支持文件的复杂内容 → 技能目录

第 2 步：创建文件

命令：

---
name: my-command
description: What this command does
argument-hint: [expected arguments]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---

# Command Title

## Workflow

### Step 1: Gather Context
...

### Step 2: Execute
...

## Success Criteria
- [ ] Expected outcome 1
- [ ] Expected outcome 2

技能：

---
name: my-skill
description: What it does. Use when [trigger conditions].
---

# Skill Title

## Quick Start
[Immediate actionable example]

## Instructions
[Core guidance]

## Examples
[Concrete input/output pairs]

第 3 步：添加参考文件（如有需要）

从 SKILL.md 链接到详细内容：

For API reference, see [reference.md](reference.md).
For form filling guide, see [forms.md](forms.md).

第 4 步：使用真实任务进行测试

1. 使用实际任务测试，而非测试场景
2. 通过 /skill-name 直接调用以验证
3. 提出与描述相符的问题，检查是否会自动触发
4. 根据实际表现进行优化

审查清单

• YAML 前置元数据有效（包含名称和描述）
• 描述包含触发关键词且具体明确
• 使用标准 Markdown 标题（而非 XML 标签）
• SKILL.md 少于 500 行
• 如果会产生副作用，则设置 disable-model-invocation: true
• 如果需要特定工具，则设置 allowed-tools
• 参考文件仅一层引用，且链接正确
• 示例具体，而非抽象
• 已使用真实任务进行测试

应避免的反模式

• 正文中使用 XML 标签 - 使用标准 Markdown 标题
• 描述含糊 - 使用明确的触发关键词
• 嵌套过深 - 参考文件与 SKILL.md 的引用层级保持一层
• 缺少调用控制 - 有副作用的工作流需要设置 disable-model-invocation: true
• 选项过多 - 提供默认选项和退出方式
• 将问题推给 Claude - 脚本应明确处理错误

参考文件

如需详细指导，请参阅：

• official-spec.md - 官方技能规范
• best-practices.md - 技能编写最佳实践

来源

• 使用技能扩展 Claude - 官方文档
• GitHub - anthropics/skills