name: creating-agent-skills description: 为创建、编写和优化 Claude Code Skills 提供专家指导。当处理 SKILL.md 文件、编写新技能、改进现有技能或理解技能结构和最佳实践时使用。

创建代理技能

本技能教授如何按照 Anthropic 官方规范创建有效的 Claude Code Skills。

核心原则

1. 技能即提示

所有提示最佳实践都适用。要清晰、直接。假设 Claude 是智能的——只添加 Claude 没有的上下文。

2. 标准 Markdown 格式

使用 YAML 前置元数据 + Markdown 正文。不使用 XML 标签——使用标准 Markdown 标题。

---
name: my-skill-name
description: 它做什么以及何时使用
---

# 我的技能名称

## 快速开始
立即可操作指导...

## 说明
分步程序...

## 示例
具体使用示例...

3. 渐进式披露

保持 SKILL.md 在 500 行以下。将详细内容拆分到参考文件中。仅加载所需内容。

my-skill/
├── SKILL.md              # 入口点（必需）
├── reference.md          # 详细文档（需要时加载）
├── examples.md           # 使用示例
└── scripts/              # 实用脚本（执行，不加载）

4. 有效描述

描述字段支持技能发现。包括技能做什么以及何时使用。以第三人称编写。

好：

description: 从 PDF 文件提取文本和表格，填写表单，合并文档。当处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。

差：

description: 帮助处理文档

技能结构

必需前置元数据

字段	必需	最大长度	描述
`name`	是	64 字符	仅小写字母、数字、连字符
`description`	是	1024 字符	它做什么以及何时使用
`allowed-tools`	否	-	Claude 可使用的工具无需询问
`model`	否	-	使用的特定模型

命名约定

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

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

避免：helper, utils, tools, anthropic-*, claude-*

正文结构

使用标准 Markdown 标题：

# 技能名称

## 快速开始
最快实现价值路径...

## 说明
Claude 遵循的核心指导...

## 示例
显示预期行为的输入/输出对...

## 高级功能
附加功能（链接到参考文件）...

## 指南
规则和约束...

你想做什么？

创建新技能 - 从零开始构建
审核现有技能 - 对照最佳实践检查
添加组件 - 添加工作流/参考/示例
获取指导 - 理解技能设计

创建新技能

步骤 1：选择类型

简单技能（单文件）：

500 行以下
自包含指导
无复杂工作流

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

SKILL.md 作为概述
参考文件用于详细文档
脚本用于实用程序

步骤 2：创建 SKILL.md

---
name: your-skill-name
description: [它做什么]。当 [触发条件] 时使用。
---

# 你的技能名称

## 快速开始

[立即可操作示例]

```[语言]
[代码示例]

说明

[核心指导]

示例

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

[结果]

指南

[约束 1]
[约束 2]


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

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

```markdown
关于 API 参考，参见 [REFERENCE.md](REFERENCE.md)。
关于表单填写指南，参见 [FORMS.md](FORMS.md)。

保持参考从 SKILL.md 一级深度。

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

脚本执行时不加载到上下文中：

## 实用脚本

提取字段：
```bash
python scripts/analyze.py input.pdf > fields.json


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

1. 用实际任务测试，而非测试场景
2. 观察 Claude 的困难之处
3. 基于真实行为优化
4. 用 Haiku、Sonnet 和 Opus 测试

## 审核现有技能

对照此清单检查：

- [ ] 有效 YAML 前置元数据（名称 + 描述）
- [ ] 描述包括触发关键词
- [ ] 使用标准 Markdown 标题（非 XML 标签）
- [ ] SKILL.md 在 500 行以下
- [ ] 参考一级深度
- [ ] 示例具体，非抽象
- [ ] 一致术语
- [ ] 无时间敏感信息
- [ ] 脚本明确处理错误

## 常见模式

### 模板模式

为一致结果提供输出模板：

```markdown
## 报告模板

```markdown
# [分析标题]

## 执行摘要
[一段概述]

## 关键发现
- 发现 1
- 发现 2

## 建议
1. [行动项]
2. [行动项]


### 工作流模式

对于复杂多步骤任务：

```markdown
## 迁移工作流

复制此清单：

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


**步骤 1：备份数据库**
运行：`./scripts/backup.sh`
...

条件模式

通过决策点指导：

## 选择方法

**创建新内容？** 遵循下面的“创建工作流”。
**编辑现有内容？** 遵循下面的“编辑工作流”。

应避免的反模式

正文中的 XML 标签 - 使用 Markdown 标题代替
模糊描述 - 用触发关键词具体化
深度嵌套 - 保持参考从 SKILL.md 一级深度
过多选项 - 提供默认方案并备选
Windows 路径 - 始终使用正斜杠
推给 Claude - 脚本应处理错误
时间敏感信息 - 使用“旧模式”部分代替

参考文件

关于详细指导，参见：

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

成功标准

结构良好的技能：

有有效 YAML 前置元数据，包含描述性名称和描述
使用标准 Markdown 标题（非 XML 标签）
保持 SKILL.md 在 500 行以下
链接到参考文件用于详细内容
包含具体示例和输入/输出对
已通过实际使用测试

来源：