Back to Details

creating-agent-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating Agent Skills

创建Agent Skills

This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
本技能将教授如何遵循Anthropic官方规范创建高效的Claude Code Skills。

Core Principles

核心原则

1. Skills Are Prompts

1. 技能即提示词

All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
所有提示词最佳实践均适用。表述清晰、直接。默认Claude具备智能——仅添加Claude未知的上下文信息。

2. Standard Markdown Format

2. 标准Markdown格式

Use YAML frontmatter + markdown body. No XML tags - use standard markdown headings.
markdown
---
name: my-skill-name
description: What it does and when to use it
---
使用YAML前置元数据+Markdown正文。禁止使用XML标签——使用标准Markdown标题。
markdown
---
name: my-skill-name
description: What it does and when to use it
---

My Skill Name

My Skill Name

Quick Start

Quick Start

Immediate actionable guidance...
Immediate actionable guidance...

Instructions

Instructions

Step-by-step procedures...
Step-by-step procedures...

Examples

Examples

Concrete usage examples...
undefined
Concrete usage examples...
undefined

3. Progressive Disclosure

3. 渐进式披露

Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
my-skill/
├── SKILL.md              # Entry point (required)
├── reference.md          # Detailed docs (loaded when needed)
├── examples.md           # Usage examples
└── scripts/              # Utility scripts (executed, not loaded)
将SKILL.md文件控制在500行以内。将详细内容拆分至参考文件中。仅加载所需内容。
my-skill/
├── SKILL.md              # Entry point (required)
├── reference.md          # Detailed docs (loaded when needed)
├── examples.md           # Usage examples
└── scripts/              # Utility scripts (executed, not loaded)

4. Effective Descriptions

4. 有效的描述

The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
Good:
yaml
description: Extracts text and tables from PDF files, fills forms, merges 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: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
糟糕示例：
yaml
description: Helps with documents

Skill Structure

技能结构

Required Frontmatter

必填前置元数据

FieldRequiredMax LengthDescription
name
Yes64 charsLowercase letters, numbers, hyphens only
description
Yes1024 charsWhat it does AND when to use it
allowed-tools
No-Tools Claude can use without asking
model
No-Specific model to use
字段是否必填最大长度描述
name
是64字符仅允许小写字母、数字、连字符
description
是1024字符需包含技能功能及适用场景
allowed-tools
否-Claude无需询问即可使用的工具
model
否-需使用的特定模型

Naming Conventions

命名规范

Use gerund form (verb + -ing) for skill names:
  • processing-pdfs
  • analyzing-spreadsheets
  • generating-commit-messages
  • reviewing-code
Avoid: 
helper
, 
utils
, 
tools
, 
anthropic-*
, 
claude-*
技能名称使用动名词形式（动词+-ing）：
  • processing-pdfs
  • analyzing-spreadsheets
  • generating-commit-messages
  • reviewing-code
需避免：
helper
, 
utils
, 
tools
, 
anthropic-*
, 
claude-*

Body Structure

正文结构

Use standard markdown headings:
markdown
undefined
使用标准Markdown标题：
markdown
undefined

Skill Name

Skill Name

Quick Start

Quick Start

Fastest path to value...
Fastest path to value...

Instructions

Instructions

Core guidance Claude follows...
Core guidance Claude follows...

Examples

Examples

Input/output pairs showing expected behavior...
Input/output pairs showing expected behavior...

Advanced Features

Advanced Features

Additional capabilities (link to reference files)...
Additional capabilities (link to reference files)...

Guidelines

Guidelines

Rules and constraints...
undefined
Rules and constraints...
undefined

What Would You Like To Do?

你想执行什么操作？

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

Creating a New Skill

创建新技能

Step 1: Choose Type

步骤1：选择类型

Simple skill (single file):
  • Under 500 lines
  • Self-contained guidance
  • No complex workflows
Progressive disclosure skill (multiple files):
  • SKILL.md as overview
  • Reference files for detailed docs
  • Scripts for utilities
简单技能（单文件）：
  • 少于500行
  • 独立指导内容
  • 无复杂工作流
渐进式披露技能（多文件）：
  • SKILL.md作为概览
  • 参考文件用于存放详细文档
  • 脚本用于实现工具功能

Step 2: Create SKILL.md

步骤2：创建SKILL.md

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

Your Skill Name

Your Skill Name

Quick Start

Quick Start

[Immediate actionable example]
[Code example]
[Immediate actionable example]
[Code example]

Instructions

Instructions

[Core guidance]
[Core guidance]

Examples

Examples

Example 1: Input: [description] Output:
[result]
Example 1: Input: [description] Output:
[result]

Guidelines

Guidelines

  • [Constraint 1]
  • [Constraint 2]
undefined
  • [Constraint 1]
  • [Constraint 2]
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).
Keep references one level deep from SKILL.md.
从SKILL.md链接到详细内容：
markdown
For API reference, see [REFERENCE.md](REFERENCE.md).
For form filling guide, see [FORMS.md](FORMS.md).
参考文件需位于SKILL.md的一级目录下。

Step 4: Add Scripts (If Needed)

步骤4：添加脚本（如有需要）

Scripts execute without loading into context:
markdown
undefined
脚本将直接执行，不会加载到上下文中：
markdown
undefined

Utility Scripts

Utility Scripts

Extract fields:
bash
python scripts/analyze.py input.pdf > fields.json
undefined
Extract fields:
bash
python scripts/analyze.py input.pdf > fields.json
undefined

Step 5: Test With Real Usage

步骤5：通过实际使用测试

  1. Test with actual tasks, not test scenarios
  2. Observe where Claude struggles
  3. Refine based on real behavior
  4. Test with Haiku, Sonnet, and Opus
  1. 使用真实任务测试，而非测试场景
  2. 观察Claude的薄弱环节
  3. 根据实际表现优化技能
  4. 使用Haiku、Sonnet和Opus模型测试

Auditing Existing Skills

审核现有技能

Check against this rubric:
  • Valid YAML frontmatter (name + description)
  • Description includes trigger keywords
  • Uses standard markdown headings (not XML tags)
  • SKILL.md under 500 lines
  • References one level deep
  • Examples are concrete, not abstract
  • Consistent terminology
  • No time-sensitive information
  • Scripts handle errors explicitly
对照以下标准检查：
  • 有效的YAML前置元数据（包含name和description）
  • 描述中包含触发关键词
  • 使用标准Markdown标题（而非XML标签）
  • SKILL.md少于500行
  • 参考文件位于一级目录下
  • 示例具体，而非抽象
  • 术语一致
  • 无时效性信息
  • 脚本明确处理错误

Common Patterns

常见模式

Template Pattern

模板模式

Provide output templates for consistent results:
markdown
undefined
提供输出模板以确保结果一致性：
markdown
undefined

Report Template

Report Template

markdown
undefined
markdown
undefined

[Analysis Title]

[Analysis Title]

Executive Summary

Executive Summary

[One paragraph overview]
[One paragraph overview]

Key Findings

Key Findings

  • Finding 1
  • Finding 2
  • Finding 1
  • Finding 2

Recommendations

Recommendations

  1. [Action item]
  2. [Action item]
undefined
  1. [Action item]
  2. [Action item]
undefined

Workflow Pattern

工作流模式

For complex multi-step tasks:
markdown
undefined
适用于复杂的多步骤任务：
markdown
undefined

Migration Workflow

Migration Workflow

Copy this checklist:
- [ ] Step 1: Backup database
- [ ] Step 2: Run migration script
- [ ] Step 3: Validate output
- [ ] Step 4: Update configuration
Step 1: Backup database Run: 
./scripts/backup.sh
...
undefined
Copy this checklist:
- [ ] Step 1: Backup database
- [ ] Step 2: Run migration script
- [ ] Step 3: Validate output
- [ ] Step 4: Update configuration
Step 1: Backup database Run: 
./scripts/backup.sh
...
undefined

Conditional Pattern

条件模式

Guide through decision points:
markdown
undefined
引导完成决策点：
markdown
undefined

Choose Your Approach

Choose Your Approach

Creating new content? Follow "Creation workflow" below. Editing existing? Follow "Editing workflow" below.
undefined
Creating new content? Follow "Creation workflow" below. Editing existing? Follow "Editing workflow" below.
undefined

Anti-Patterns to Avoid

需避免的反模式

  • XML tags in body - Use markdown headings instead
  • Vague descriptions - Be specific with trigger keywords
  • Deep nesting - Keep references one level from SKILL.md
  • Too many options - Provide a default with escape hatch
  • Windows paths - Always use forward slashes
  • Punting to Claude - Scripts should handle errors
  • Time-sensitive info - Use "old patterns" section instead
  • 正文使用XML标签 - 改用Markdown标题
  • 模糊的描述 - 明确包含触发关键词
  • 深层嵌套 - 参考文件需位于SKILL.md的一级目录下
  • 过多选项 - 提供默认方案及备选路径
  • Windows路径 - 始终使用正斜杠
  • 依赖Claude处理 - 脚本应明确处理错误
  • 时效性信息 - 改用“旧模式”章节存放

Reference Files

参考文件

For detailed guidance, see:
  • official-spec.md - Anthropic's official skill specification
  • best-practices.md - Skill authoring best practices
如需详细指导，请查看：

Success Criteria

—
A well-structured skill:
  • Has valid YAML frontmatter with descriptive name and description
  • Uses standard markdown headings (not XML tags)
  • Keeps SKILL.md under 500 lines
  • Links to reference files for detailed content
  • Includes concrete examples with input/output pairs
  • Has been tested with real usage
Sources:
—