Agent Skills开发教程

本教程基于Skill Creator核心指南编写，将详细讲解Agent Skills（以下简称“Skill”）的定义、核心原则、结构组成、设计理念及完整开发流程，帮助你快速掌握Skill开发方法，打造可扩展Claude能力的专业化模块。

一、Skill基础认知（About Skills）

Skill是模块化、独立的功能包，通过提供专业知识、工作流程和工具集成，扩展Claude的核心能力。你可以将其理解为“特定领域的入职指南”——它能让通用型Claude转变为具备专属流程知识的专业代理，这些流程知识是通用模型无法完全掌握的。

1.1 Skill的核心价值

• 专业工作流程：针对特定领域的多步骤操作流程（如PDF处理、API调用流程等）。

• 工具集成能力：提供特定文件格式（如DOCX、PDF）或API的操作说明。

• 领域专业知识：包含公司专属知识、数据 schema、业务逻辑等定制化内容。

• 捆绑资源包：整合脚本、参考文档、资产文件等，支撑复杂重复任务的高效执行。

二、Skill开发核心原则（Core Principles）

遵循以下原则可确保Skill的高效性、易用性和上下文友好性，是开发优质Skill的基础。

2.1 简洁为王（Concise is Key）

上下文窗口是宝贵的公共资源，Skill需与系统提示、对话历史、其他Skill元数据及用户请求共享该窗口。开发时需牢记：

• 默认假设“Claude已足够智能”，仅添加Claude不具备的上下文信息。

• 对每段信息进行核验：“Claude真的需要这段解释吗？”“这段内容的Token成本是否合理？”

• 优先使用简洁示例，而非冗长说明。

2.2 设置适当自由度（Set Appropriate Degrees of Freedom）

根据任务的脆弱性和可变性，匹配对应的指令 specificity 级别，如同为Claude规划行动路径——悬崖边的窄桥需严格护栏（低自由度），开阔田野可自由探索（高自由度）。

• 高自由度（文本型指令）：适用于多种方案均有效、决策依赖上下文或需启发式引导的场景（如创意文案优化、通用咨询）。

• 中自由度（伪代码/带参数脚本）：适用于有优选模式、允许适度变体或配置影响行为的场景（如带参数的数据分析脚本）。

• 低自由度（特定脚本/少参数）：适用于操作脆弱易出错、一致性至关重要或需严格遵循固定序列的场景（如系统部署步骤、敏感数据处理）。

三、Skill的结构组成（Anatomy of a Skill）

每个Skill必须包含SKILL.md文件（必需），可选择性包含捆绑资源。标准目录结构如下：

skill-name/
├── SKILL.md (必需)
│   ├── YAML前置元数据 (必需)
│   │   ├── name: (必需)
│   │   └── description: (必需)
│   └── Markdown指令 (必需)
└── 捆绑资源 (可选)
    ├── scripts/          - 可执行代码（Python/Bash等）
    ├── references/       - 按需加载的参考文档
    └── assets/           - 输出用资源（模板、图标等）

3.1 必需组件：SKILL.md

该文件是Skill的核心，包含Claude识别和使用Skill所需的全部关键信息，分为前置元数据和正文两部分。

3.1.1 前置元数据（YAML格式）

仅包含两个必需字段，是Claude判断Skill用途和触发时机的核心依据，需清晰、全面描述。

• name：Skill名称（简洁唯一，如“pdf-editor”“bigquery-skill”）。

• description：Skill描述（核心触发机制），需同时说明“Skill功能”和“触发场景”，避免冗余。示例：“Comprehensive document creation, editing, and analysis with support for tracked changes. Use when Claude needs to work with .docx files for creating/editing documents or handling tracked changes.”

注意：禁止添加其他YAML字段，仅保留name和description。

3.1.2 正文（Markdown格式）

包含Skill使用的指令和指南，仅在Skill触发后才会加载。写作需遵循“命令式/不定式语气”（如“Extract text with pdfplumber”），聚焦核心流程，避免无关信息。

3.2 可选组件：捆绑资源

根据Skill需求选择性添加，用于存储可复用内容，减少正文冗余并提升执行效率。

3.2.1 scripts/（可执行脚本目录）

存储Python、Bash等可执行代码，适用于“重复执行”或“需确定性可靠性”的任务（如PDF旋转、数据清洗）。

• 使用场景：相同代码需重复编写、任务要求结果可确定。

• 示例：scripts/rotate_pdf.py（PDF旋转脚本）。

• 注意：脚本需实际运行测试，确保无bug；若存在多个相似脚本，可抽样测试以平衡效率。

3.2.2 references/（参考文档目录）

存储需按需加载的参考资料，用于支撑Claude的决策和操作（如数据 schema、API文档、公司政策）。

• 使用场景：文档内容较详细、仅特定场景需用到。

• 示例：references/schema.md（数据库表结构）、references/api_docs.md（API说明）。

• 最佳实践：① 大型文件（>10k字）需在SKILL.md中添加grep搜索模式；② 信息仅存于一处（SKILL.md或参考文件，不重复）；③ 仅将核心流程保留在SKILL.md，详细内容迁移至参考文件。

3.2.3 assets/（输出资产目录）

存储用于“最终输出”的文件，不加载到上下文（如模板、图标、字体、前端脚手架）。

• 使用场景：Skill输出需依赖固定资源（如生成PPT需模板、输出文档需logo）。

• 示例：assets/logo.png（品牌图标）、assets/frontend-template/（React项目模板）。

3.3 禁止包含的文件

Skill仅需包含支撑功能的核心文件，禁止添加无关文档，包括但不限于：README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md等。此类文件会增加冗余并造成混淆。

四、渐进式披露设计原则（Progressive Disclosure Design Principle）

该原则通过“三级加载机制”高效管理上下文，避免Skill占用过多Token，核心是“按需加载、最小化上下文”。

4.1 三级加载系统

1. 元数据（name + description）：始终在上下文（约100词，占用极少Token）。

2. SKILL.md正文：Skill触发时加载（建议<5k字，控制在500行内）。

3. 捆绑资源：Claude根据需求按需加载（无字数限制，脚本可执行无需加载上下文）。

4.2 三种核心模式

当SKILL.md正文接近500行限制时，需拆分内容至参考文件，并在正文中明确引用，确保Claude知晓资源位置和使用时机。

模式1：高级指南+参考文件

正文保留核心流程，高级功能链接至对应参考文件，示例：

# PDF Processing
## Quick start
Extract text with pdfplumber:
[简单代码示例]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

模式2：按领域组织资源

多领域Skill按领域拆分参考文件，避免加载无关内容，示例目录结构：

bigquery-skill/
├── SKILL.md (概述+导航)
└── reference/
    ├── finance.md (财务指标)
    ├── sales.md (销售数据)
    ├── product.md (产品API)
    └── marketing.md (营销活动)

模式3：条件化细节展示

正文展示基础内容，高级细节链接至参考文件，示例：

# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

关键注意事项

• 参考文件需直接链接自SKILL.md，避免深层嵌套。

• 长参考文件（>100行）需在顶部添加目录，方便Claude快速预览范围。

五、Skill开发完整流程（Skill Creation Process）

Skill开发需遵循以下6个步骤，按顺序执行（无明确理由不得跳过），确保Skill质量和可用性。

步骤1：通过具体示例理解Skill需求

仅当Skill用途和使用模式已完全明确时可跳过，即使优化现有Skill，此步骤也有参考价值。核心是通过“具体示例”明确Skill功能和触发场景。

• 获取示例：直接收集用户真实使用案例，或生成示例后经用户验证。

• 核心问题（以高中语文作文评分SKILL为例）：

  • Skill需支持哪些功能？（作文评分，点评，改进建议等）f

  • 用户会如何触发Skill？（给出一篇作文，要求打分等）

• 注意：避免一次性提问过多，优先聚焦核心问题，逐步跟进补充。

完成标志：清晰掌握Skill需支持的所有功能和触发场景。

步骤2：规划可复用Skill内容

分析步骤1中的具体示例，提炼可复用资源（脚本、参考文件、资产），将“重复任务”转化为“可复用组件”，降低后续维护成本。

示例分析：

• PDF编辑Skill：旋转PDF需重复编写代码 → 规划scripts/rotate_pdf.py。

• 前端项目构建Skill：创建项目需重复编写HTML/React模板 → 规划assets/frontend-template/。

• BigQuery查询Skill：需反复查阅表结构 → 规划references/schema.md。

• 高中语文作文评分SKILL：需要有一个作文评分标准 规划一个评分标准.md 需要一个字数统计的py脚本

输出：可复用资源清单（明确每个资源的类型、用途和存储路径）。

步骤3：初始化Skill（Initialize the Skill）

仅当Skill已存在（需迭代或打包）时可跳过，新Skill必须通过初始化脚本创建，确保目录结构标准化，提升开发效率。

核心操作：运行init_skill.py脚本，生成标准化Skill模板。

scripts/init_skill.py <skill-name> --path <output-directory>

脚本功能：

• 在指定路径创建Skill目录（skill-name）。

• 生成带前置元数据和TODO占位符的SKILL.md模板。

• 创建scripts/、references/、assets/目录及示例文件。

后续操作：根据需求自定义或删除生成的模板文件（示例文件仅用于展示结构，非必需）。

步骤4：编辑Skill（Edit the Skill）

基于初始化模板，实现可复用资源并完善SKILL.md，核心是“为Claude编写指南”——需提供非显而易见但有价值的信息（流程、注意事项、资源位置）。

4.1 优先实现可复用资源

根据步骤2的规划，编写scripts/、references/、assets/中的内容：

• 脚本：编写后需运行测试，确保无bug。

• 参考文件：按领域/功能分类，添加目录（长文件）。

• 资产：放入输出所需的模板、图标等文件。

注意：删除无需使用的示例文件（如Skill不涉及脚本，可删除scripts/目录下的示例）。

4.2 完善SKILL.md

• 前置元数据：完善name和description，确保触发场景清晰。

• 正文：按“核心流程+资源引用”编写，使用命令式语气，链接参考文件和脚本（如“See FORMS.md for form filling guide”）。

步骤5：打包Skill（Package the Skill）

Skill开发完成后，需打包为可分发的.skill文件（本质是zip压缩包），打包前会自动验证Skill合法性。

核心操作：运行package_skill.py脚本。

# 基础打包（输出至当前目录）
scripts/package_skill.py <path/to/skill-folder>

# 指定输出目录（输出至dist目录）
scripts/package_skill.py <path/to/skill-folder> ./dist

脚本流程：

1. 验证（Validation）：自动检查以下内容，验证失败则报错并退出：

   • YAML前置元数据格式及必需字段（name、description）。

   • Skill命名规范和目录结构。

   • description的完整性和质量。

   • 文件组织和资源引用的有效性。

2. 打包（Packaging）：验证通过后，生成以Skill名称命名的.skill文件（如pdf-editor.skill），包含所有核心文件和目录结构。

注意：需修复所有验证错误后，重新运行打包命令。

步骤6：迭代优化（Iterate）

Skill发布后，需基于真实使用场景持续优化，解决使用中的问题和低效点，形成“使用-反馈-优化”的闭环。

迭代流程：

1. 在真实任务中使用Skill。

2. 记录Skill的不足（如流程繁琐、触发不精准、资源缺失）。

3. 明确SKILL.md或捆绑资源的修改方向。

4. 实施修改并测试，重复步骤5打包发布。

六、总结

Agent Skills开发的核心是“简洁、高效、可复用”——通过遵循核心原则、标准化结构、渐进式披露设计和完整开发流程，可打造出能精准扩展Claude能力的专业Skill。关键在于聚焦“Claude真正需要的信息”，避免冗余，让Skill在上下文友好的前提下发挥最大价值。

（注：参考来源：Anthropics）