Back to Details

create-agent-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating Skills & Commands

技能与命令创建指南

This skill teaches how to create effective Claude Code skills following the official specification from code.claude.com/docs/en/skills.
本技能将指导你如何遵循code.claude.com/docs/en/skills官方规范，创建高效的Claude Code技能。

Commands and Skills Are Now The Same Thing

命令与技能现已统一

Custom slash commands have been merged into skills. A file at 
.claude/commands/review.md
and a skill at 
.claude/skills/review/SKILL.md
both create 
/review
and work the same way. Existing 
.claude/commands/
files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
If a skill and a command share the same name, the skill takes precedence.
自定义斜杠命令已整合到技能体系中。
.claude/commands/review.md
路径下的命令文件，与
.claude/skills/review/SKILL.md
路径下的技能文件，都会生成
/review
命令，且功能完全一致。已有的
.claude/commands/
目录下的文件仍可正常使用。技能新增了可选特性：支持附属文件的目录结构、控制调用的前置元数据（frontmatter），以及自动上下文加载功能。
若技能与命令重名，技能将优先生效。

When To Create What

场景选择建议

Use a command file (
commands/name.md
) when:
  • Simple, single-file workflow
  • No supporting files needed
  • Task-oriented action (deploy, commit, triage)
Use a skill directory (
skills/name/SKILL.md
) when:
  • Need supporting reference files, scripts, or templates
  • Background knowledge Claude should auto-load
  • Complex enough to benefit from progressive disclosure
Both use identical YAML frontmatter and markdown content format.
使用命令文件（
commands/name.md
）的场景：
  • 简单的单文件工作流
  • 无需附属文件
  • 面向特定任务的操作（如部署、提交、问题分类）
使用技能目录（
skills/name/SKILL.md
）的场景：
  • 需要配套的参考文件、脚本或模板
  • 需要Claude自动加载背景知识
  • 逻辑复杂，适合采用渐进式内容披露方式
两者均使用完全相同的YAML前置元数据与Markdown内容格式。

Standard Markdown Format

标准Markdown格式

Use YAML frontmatter + markdown body with standard markdown headings. Keep it clean and direct.
markdown
---
name: my-skill-name
description: What it does and when to use it
---
采用YAML前置元数据 + Markdown正文的结构，使用标准Markdown标题。保持内容简洁直接。
markdown
---
name: my-skill-name
description: 技能功能及适用场景
---

My Skill Name

我的技能名称

Quick Start

快速开始

Immediate actionable guidance...
可立即执行的操作指引...

Instructions

详细步骤

Step-by-step procedures...
分步操作流程...

Examples

使用示例

Concrete usage examples...
undefined
具体的使用案例...
undefined

Frontmatter Reference

前置元数据参考

All fields are optional. Only 
description
is recommended.
FieldRequiredDescription
name
NoDisplay name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name.
description
RecommendedWhat it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars.
argument-hint
NoHint shown during autocomplete. Example: 
[issue-number]
disable-model-invocation
NoSet 
true
to prevent Claude auto-loading. Use for manual workflows like 
/deploy
, 
/commit
. Default: 
false
.
user-invocable
NoSet 
false
to hide from 
/
menu. Use for background knowledge. Default: 
true
.
allowed-tools
NoTools Claude can use without permission prompts. Example: 
Read, Bash(git *)
model
NoModel to use. Options: 
haiku
, 
sonnet
, 
opus
.
context
NoSet 
fork
to run in isolated subagent context.
agent
NoSubagent type when 
context: fork
. Options: 
Explore
, 
Plan
, 
general-purpose
, or custom agent name.
所有字段均为可选，仅推荐填写
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名称。

Invocation Control

调用控制规则

FrontmatterUser can invokeClaude can invokeWhen loaded
(default)YesYesDescription always in context, full content loads when invoked
disable-model-invocation: true
YesNoDescription not in context, loads only when user invokes
user-invocable: false
NoYesDescription always in context, loads when relevant
Use 
disable-model-invocation: true
 for workflows with side effects: 
/deploy
, 
/commit
, 
/triage-prs
, 
/send-slack-message
. You don't want Claude deciding to deploy because your code looks ready.
Use 
user-invocable: false
 for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
前置元数据配置用户可调用Claude可自动调用加载时机
默认配置是是描述始终在上下文中，触发时加载完整内容
disable-model-invocation: true
是否描述不在上下文中，仅当用户主动调用时加载
user-invocable: false
否是描述始终在上下文中，相关场景下自动加载
建议为带有副作用的工作流设置
disable-model-invocation: true
：如
/deploy
、
/commit
、
/triage-prs
、
/send-slack-message
。你肯定不希望Claude因为代码看起来没问题就自动执行部署操作。
建议为背景知识类内容设置
user-invocable: false
：如编码规范、领域上下文、遗留系统文档等，这些并非用户可执行的操作。

Dynamic Features

动态特性

Arguments

参数处理

Use 
$ARGUMENTS
placeholder for user input. If not present in content, arguments are appended automatically.
yaml
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.
Access individual args: 
$ARGUMENTS[0]
or shorthand 
$0
, 
$1
, 
$2
.
使用
$ARGUMENTS
占位符接收用户输入。若内容中未包含该占位符，参数将自动追加到内容末尾。
yaml
---
name: fix-issue
description: 修复GitHub问题
disable-model-invocation: true
---

按照编码标准修复GitHub问题$ARGUMENTS。
可通过
$ARGUMENTS[0]
或简写
$0
、
$1
、
$2
访问单个参数。

Dynamic Context Injection

动态上下文注入

The 
!`command`
syntax runs shell commands before content is sent to Claude:
yaml
---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---
使用
!`command`
语法可在内容发送给Claude前执行Shell命令：
yaml
---
name: pr-summary
description: 总结Pull Request中的变更
context: fork
agent: Explore
---

Context

上下文信息

  • PR diff: !
    gh pr diff
  • Changed files: !
    gh pr diff --name-only
Summarize this pull request...
undefined
  • PR差异：!
    gh pr diff
  • 修改文件：!
    gh pr diff --name-only
总结本次Pull Request的变更内容...
undefined

Running in a Subagent

子Agent独立运行

Add 
context: fork
to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
yaml
---
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
添加
context: fork
配置可让技能在独立上下文运行。技能内容将作为子Agent的提示词，不会包含对话历史。
yaml
---
name: deep-research
description: 深入研究指定主题
context: fork
agent: Explore
---

深入研究$ARGUMENTS：
1. 查找相关文件
2. 分析代码
3. 总结研究结果

Progressive Disclosure

渐进式内容披露

Keep SKILL.md under 500 lines. Split detailed content into reference files:
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)
Link from SKILL.md: 
For API details, see [reference.md](reference.md).
Keep references one level deep from SKILL.md. Avoid nested chains.
保持SKILL.md文件不超过500行。将详细内容拆分到参考文件中：
my-skill/
├── SKILL.md           # 入口文件（必填，包含概述与导航）
├── reference.md       # 详细文档（按需加载）
├── examples.md        # 使用示例（按需加载）
└── scripts/
    └── helper.py      # 实用脚本（可执行，不加载为上下文）
在SKILL.md中添加链接：
API详情请参考[reference.md](reference.md)。
参考文件需保持与SKILL.md同级，避免嵌套层级过深。

Effective Descriptions

高效描述编写技巧

The description enables skill discovery. Include both what it does and when to use it.
Good:
yaml
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.
Bad:
yaml
description: Helps with documents
描述是技能被自动发现的关键，需同时包含功能与触发场景。
优秀示例：
yaml
description: 从PDF文件中提取文本与表格、填充表单、合并文档。适用于处理PDF文件或用户提及PDF、表单、文档提取的场景。
糟糕示例：
yaml
description: 处理文档

What Would You Like To Do?

你想执行以下哪项操作？

  1. Create new skill - Build from scratch
  2. Create new command - Build a slash command
  3. Audit existing skill - Check against best practices
  4. Add component - Add workflow/reference/example
  5. Get guidance - Understand skill design
  1. 创建新技能 - 从零开始构建
  2. 创建新命令 - 构建斜杠命令
  3. 审计现有技能 - 对照最佳实践检查
  4. 添加组件 - 添加工作流/参考内容/示例
  5. 获取指导 - 理解技能设计思路

Creating a New Skill or Command

创建新技能或命令的步骤

Step 1: Choose Type

步骤1：选择类型

Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
  • Manual workflow → command with 
    disable-model-invocation: true
  • Background knowledge → skill without 
    disable-model-invocation
  • Complex with supporting files → skill directory
思考：这是手动工作流（如部署、提交、分类）还是背景知识（如规范、模式）？
  • 手动工作流 → 使用命令文件并设置
    disable-model-invocation: true
  • 背景知识 → 使用技能文件，不设置
    disable-model-invocation
  • 复杂且需附属文件 → 使用技能目录

Step 2: Create the File

步骤2：创建文件

Command:
markdown
---
name: my-command
description: What this command does
argument-hint: [expected arguments]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---
命令文件示例：
markdown
---
name: my-command
description: 该命令的功能
argument-hint: [预期参数]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---

Command Title

命令标题

Workflow

工作流

Step 1: Gather Context

步骤1：收集上下文

...
...

Step 2: Execute

步骤2：执行操作

...
...

Success Criteria

成功标准

  • Expected outcome 1
  • Expected outcome 2

**Skill:**
```markdown
---
name: my-skill
description: What it does. Use when [trigger conditions].
---
  • 预期结果1
  • 预期结果2

**技能文件示例：**
```markdown
---
name: my-skill
description: 技能功能。适用于[触发条件]场景。
---

Skill Title

技能标题

Quick Start

快速开始

[Immediate actionable example]
[可立即执行的示例]

Instructions

操作指引

[Core guidance]
[核心指导内容]

Examples

使用示例

[Concrete input/output pairs]
undefined
[具体的输入/输出示例]
undefined

Step 3: Add Reference Files (If Needed)

步骤3：添加参考文件（如需）

Link from SKILL.md to detailed content:
markdown
For API reference, see [reference.md](reference.md).
For form filling guide, see [forms.md](forms.md).
在SKILL.md中链接到详细内容：
markdown
API参考请见[reference.md](reference.md)。
表单填充指南请见[forms.md](forms.md)。

Step 4: Test With Real Usage

步骤4：实际场景测试

  1. Test with actual tasks, not test scenarios
  2. Invoke directly with 
    /skill-name
    to verify
  3. Check auto-triggering by asking something that matches the description
  4. Refine based on real behavior
  1. 在真实任务中测试，而非仅测试场景
  2. 通过
    /skill-name
    直接调用以验证功能
  3. 通过提问匹配描述的内容，检查自动触发是否正常
  4. 根据实际表现优化技能

Audit Checklist

审计检查清单

  • Valid YAML frontmatter (name + description)
  • Description includes trigger keywords and is specific
  • Uses standard markdown headings (not XML tags)
  • SKILL.md under 500 lines
  • disable-model-invocation: true
    if it has side effects
  • allowed-tools
    set if specific tools needed
  • References one level deep, properly linked
  • Examples are concrete, not abstract
  • Tested with real usage
  • 有效的YAML前置元数据（包含name与description）
  • 描述包含触发关键词且具体明确
  • 使用标准Markdown标题（而非XML标签）
  • SKILL.md文件不超过500行
  • 带有副作用的工作流已设置
    disable-model-invocation: true
  • 已根据需求配置
    allowed-tools
  • 参考文件与SKILL.md同级，链接正确
  • 示例具体，非抽象描述
  • 已在真实场景中测试

Anti-Patterns to Avoid

需避免的反模式

  • XML tags in body - Use standard markdown headings
  • Vague descriptions - Be specific with trigger keywords
  • Deep nesting - Keep references one level from SKILL.md
  • Missing invocation control - Side-effect workflows need 
    disable-model-invocation: true
  • Too many options - Provide a default with escape hatch
  • Punting to Claude - Scripts should handle errors explicitly
  • 正文使用XML标签 - 应使用标准Markdown标题
  • 描述模糊 - 需明确包含触发关键词
  • 参考文件嵌套过深 - 保持与SKILL.md同级
  • 未配置调用控制 - 有副作用的工作流必须设置
    disable-model-invocation: true
  • 选项过多 - 提供默认选项及扩展入口即可
  • 依赖Claude自动处理 - 脚本应显式处理错误

Reference Files

参考文件

For detailed guidance, see:
  • official-spec.md - Official skill specification
  • best-practices.md - Skill authoring best practices
如需详细指导，请查看：
  • official-spec.md - 官方技能规范
  • best-practices.md - 技能编写最佳实践

Sources

资料来源