creating-agent-skills

创建 Agent 技能

本技能将指导你如何按照 Anthropic 的官方规范创建有效的 Claude Code 技能。

核心原则

1. 技能就是提示词

所有提示词最佳实践都适用。表达清晰、直接。假设 Claude 足够聪明——只补充 Claude 不具备的上下文。

2. 标准 Markdown 格式

使用 YAML frontmatter + Markdown 正文。不要使用 XML 标签——使用标准 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...

3. 渐进式披露

将 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. 有效的描述

description 字段有助于发现技能。既要说明技能的功能，也要说明何时使用。使用第三人称撰写。

好例子：

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.

坏例子：

description: Helps with documents

技能结构

必需的 Frontmatter

字段	必需	最大长度	描述
name	是	64 个字符	仅限小写字母、数字和连字符
description	是	1024 个字符	说明功能以及使用时机
allowed-tools	否	-	Claude 无需询问即可使用的工具
model	否	-	要使用的特定模型

命名约定

技能名称使用动名词形式（动词 + -ing）：

• processing-pdfs
• analyzing-spreadsheets
• generating-commit-messages
• reviewing-code

避免使用：helper、utils、tools、anthropic-*、claude-*

正文结构

使用标准 Markdown 标题：

# Skill Name

## Quick Start
Fastest path to value...

## Instructions
Core guidance Claude follows...

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

## Advanced Features
Additional capabilities (link to reference files)...

## Guidelines
Rules and constraints...

你想做什么？

1. 创建新技能 - 从头开始构建
2. 审查现有技能 - 对照最佳实践进行检查
3. 添加组件 - 添加工作流、参考资料或示例
4. 获取指导 - 了解技能设计

创建新技能

第 1 步：选择类型

简单技能（单个文件）：

• 少于 500 行
• 指导内容自成一体
• 没有复杂工作流

渐进式披露技能（多个文件）：

• 以 SKILL.md 作为概览
• 使用参考文件存放详细文档
• 使用脚本提供实用功能

第 2 步：创建 SKILL.md

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

# Your Skill Name

## Quick Start

[Immediate actionable example]

```[language]
[Code example]

说明

[核心指导]

示例

示例 1： 输入：[描述] 输出：

[result]

指南

• [约束 1]
• [约束 2]

### Step 3: Add Reference Files (If Needed)

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 最多相隔一级。

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

执行脚本时无需将其加载到上下文中：

## Utility Scripts

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

### Step 5: Test With Real Usage

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

## 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

## Common Patterns

### Template Pattern

Provide output templates for consistent results:

```markdown
## Report Template

```markdown
# [Analysis Title]

## Executive Summary
[One paragraph overview]

## Key Findings
- Finding 1
- Finding 2

## Recommendations
1. [Action item]
2. [Action item]

### Workflow Pattern

For complex multi-step tasks:

```markdown
## Migration Workflow

Copy this checklist:

• 第 1 步：备份数据库
• 第 2 步：运行迁移脚本
• 第 3 步：验证输出
• 第 4 步：更新配置

**Step 1: Backup database**
Run: `./scripts/backup.sh`
...

条件模式

针对决策点提供指导：

## Choose Your Approach

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

应避免的反模式

• 在正文中使用 XML 标签 - 改用 Markdown 标题
• 描述含糊 - 明确列出触发关键词
• 嵌套过深 - 参考文件与 SKILL.md 之间最多相隔一级
• 选项过多 - 提供默认选项，并允许用户选择其他方案
• 使用 Windows 路径 - 始终使用正斜杠
• 将任务推给 Claude - 脚本应处理错误
• 包含时效性信息 - 改用“旧模式”部分

参考文件

详细指导请参阅：

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

成功标准

结构良好的技能：

• 包含有效的 YAML frontmatter，且名称和描述清晰
• 使用标准 Markdown 标题（而非 XML 标签）
• 将 SKILL.md 控制在 500 行以内
• 链接到包含详细内容的参考文件
• 提供具体的输入/输出示例
• 已在实际使用中经过测试

来源：

• Agent Skills - Claude Code Docs
• Skill authoring best practices
• GitHub - anthropics/skills