Claude Skill 编写完全指南

📍 位置：Skill编写指南 / 0-完全指南 📌 核心发现：Skill 本质是「专门化提示模板」而非可执行代码；Description 是唯一的发现和选中依据；渐进式加载机制（三层）让 Skill 省 Token 且自治 📥 输入：Anthropic 官方 33 页指南 + 官方文档 + 社区深度分析 + AEO 优化技巧 📤 流向：独立完整参考文档，无后续收敛文件

基于 Anthropic 官方 33 页指南 + 社区深度分析 + AEO 优化技巧 调研日期：2026-03-18

一、Skill 是什么？——第一性原理

1.1 本质定义

Skill 不是可执行代码，而是专门化提示模板，通过对话上下文注入来修改 Claude 处理后续请求的方式。

“Skills 通过注入指令来准备 Claude 解决问题，而非直接解决问题。“

1.2 Skill vs API vs MCP

Skill 的核心优势 = 极度克制 + 高度自治：

• 平时：只暴露 name + description（几十字的”简历”）
• 匹配时：动态加载 SKILL.md 完整内容
• 深度使用时：按需读取 references/、scripts/ 等辅助文件

MCP 是「专业厨房」（工具连接），Skill 是「菜谱」（嵌入最佳实践的工作流）。

1.3 渐进式加载机制（Progressive Disclosure）

Skill 的 Token 消耗分三层递进：

第 1 层：前置元数据（name + description）
         → 始终加载，用于决策匹配
         → 成本：几十个 Token

第 2 层：SKILL.md 正文
         → 仅当 Claude 判断任务匹配时加载
         → 成本：数百~数千 Token

第 3 层：辅助资源（references/、scripts/ 等）
         → 仅当执行过程中需要时按需读取
         → 成本：按需消耗

核心理念：Context Window 是公共资源。你的 Skill 与系统提示、对话历史、其他 Skill 共享上下文窗口。

二、Skill 文件结构

2.1 目录结构

my-skill/
├── SKILL.md              # 核心文件（必需）
├── scripts/              # 可选：可执行脚本
│   ├── analyze.py
│   └── validate.sh
├── references/           # 可选：参考文档
│   ├── api-docs.md
│   └── schema.md
└── assets/               # 可选：模板和资源
    └── template.json

关键规则：

• 文件夹名必须使用 kebab-case（如 pdf-processing）
• 不要在 Skill 文件夹内放 README.md（文档写在 SKILL.md 或 references/ 中）
• Skill 名称不能包含 “claude” 或 “anthropic”（保留词）

2.2 SKILL.md 结构

---
name: my-skill-name          # 必填，kebab-case，最大64字符
description: |                # 必填，最大1024字符
  做什么 + 什么时候用。第三人称。
  包含关键触发词。
license: MIT                  # 可选
compatibility:                # 可选
  platforms:
    - claude-ai
    - claude-code
    - api
metadata:                     # 可选
  author: your-name
  version: "1.0.0"
  mcp-server: ServerName      # 如果需要 MCP
---

# Skill 标题

## 快速开始
[核心用法，最简洁的上手方式]

## 工作流程
[详细的步骤说明]

## 高级功能
**详细说明**: 见 [references/advanced.md](references/advanced.md)
**API 参考**: 见 [references/api.md](references/api.md)

2.3 YAML Frontmatter 字段规范

三、核心设计原则

3.1 简洁至上——Claude 已经很聪明

默认假设：只添加 Claude 还不知道的信息。

对每段内容问三个问题：

1. “Claude 真的需要这个解释吗？”
2. “能不能假设 Claude 已经知道这个？”
3. “这段话值得消耗它的 Token 成本吗？”

正面示例（约 50 Token）：

## 提取 PDF 文本
使用 pdfplumber：
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

反面示例（约 150 Token）：

## 提取 PDF 文本
PDF（Portable Document Format）是一种常见的文件格式，包含文本、
图片和其他内容。要从 PDF 中提取文本，你需要使用一个库。有很多
库可以用于 PDF 处理，但 pdfplumber 是推荐的，因为它易于使用...

3.2 设定恰当的自由度

根据任务的脆弱性和可变性，匹配不同的指令精确度：

类比：把 Claude 想象成走一条路的机器人——

• 悬崖上的窄桥：只有一条安全路 → 给精确指令（低自由度）
• 开阔无障碍的原野：多条路都能到达 → 给方向性指导（高自由度）

3.3 可组合性

• Skill 应能与其他 Skill 共存，不假设独占性
• 不要占用过多上下文窗口
• 保持 SKILL.md 正文在 500 行以内（约 5000 Token）

3.4 跨平台可移植性

Skill 应在 Claude.ai、Claude Code、API 中表现一致：

• 使用正斜杠路径（scripts/helper.py，非 scripts\helper.py）
• 不使用硬编码绝对路径
• 明确声明依赖包

四、编写高效 Description 的技巧

Description 是 Skill 被发现和选中的唯一依据。Claude 从可能 100+ 个 Skill 中，仅凭 description 决定使用哪个。

4.1 必须用第三人称

Description 会被注入系统提示，人称不一致会导致发现问题。

# 正确
description: "处理 Excel 文件并生成报告"

# 错误
description: "我可以帮你处理 Excel 文件"
description: "你可以用这个来处理 Excel 文件"

4.2 必须包含「做什么」+「何时用」

# 正确：具体且包含触发词
description: >
  从 PDF 文件中提取文本和表格，填写表单，合并文档。
  当处理 PDF 文件或用户提到 PDF、表单、文档提取时使用。

# 错误：模糊
description: "处理文档"
description: "帮助处理数据"

4.3 包含关键触发词

在 description 中嵌入用户可能使用的各种表达方式：

description: >
  生成 Git 提交信息。当用户需要帮助编写 commit message、
  审查 staged changes、提交代码时使用。
  触发词：提交、commit、git commit、提交信息。

五、五大设计模式

模式 1：顺序工作流编排（Sequential Workflow）

适用：步骤有先后依赖，前一步输出是后一步输入。

## 客户注册流程

1. 创建账户 → 2. 配置支付 → 3. 设置订阅 → 4. 发送欢迎邮件

每步完成后验证再进入下一步。
如果任何步骤失败，执行回滚。

关键：记录回滚程序。

模式 2：多 MCP 协调（Multi-MCP Coordination）

适用：工作流跨越多个外部服务。

## 设计交付流程

Figma 导出 → Drive 上传 → Linear 创建任务 → Slack 通知

使用完全限定工具名：
- Figma:export_assets
- GoogleDrive:upload_file
- Linear:create_issue
- Slack:send_message

关键：阶段间分离清晰，跨阶段前验证。

模式 3：迭代改进（Iterative Refinement）

适用：需要通过反复循环提升质量。

## 内容审核流程

1. 生成初稿
2. 运行验证脚本 → 检查质量标准
3. 如果不通过 → 修正 → 回到步骤 2
4. 通过 → 输出最终版本

终止条件：通过所有检查 OR 达到 3 次迭代上限

关键：定义明确的质量标准、验证脚本、终止条件（防止无限循环）。

模式 4：上下文感知工具选择（Context-aware Tool Selection）

适用：根据输入特征路由到不同工具。

## 文档修改

判断修改类型：

**创建新内容？** → 使用 docx-js 库从零构建
**编辑现有内容？** → 解包 → 修改 XML → 验证 → 重新打包

模式 5：领域特定智能（Domain-specific Intelligence）

适用：需要治理或合规的领域工作流。

## 金融数据查询

规则：
- 始终排除测试账户（account_type != 'test'）
- 金额字段使用 DECIMAL，不使用 FLOAT
- 所有查询必须包含日期范围过滤

模式 6：Problem-first vs Tool-first 设计决策

在设计 Skill 前，先确定你的设计出发点：

选择原则：

• 大多数业务场景用 Problem-first（用户要结果）
• 技术基础设施场景用 Tool-first（用户要标准化流程）
• 不确定时，默认 Problem-first——用户关心的是”做什么”，不是”用什么”

模式 7：四种常见工作流模式

选择匹配的模式可以帮助你确定 allowed-tools 的最小权限范围。

六、工作流与反馈闭环

6.1 复杂任务使用检查清单

## 研究综合工作流

复制此清单并跟踪进度：

\`\`\`
研究进度：
- [ ] 步骤 1: 阅读所有源文档
- [ ] 步骤 2: 识别关键主题
- [ ] 步骤 3: 交叉验证论点
- [ ] 步骤 4: 创建结构化总结
- [ ] 步骤 5: 验证引用
\`\`\`

6.2 反馈闭环模式

核心模式：运行验证 → 修正错误 → 重复

## 文档编辑流程

1. 编辑 document.xml
2. **立即验证**: `python scripts/validate.py unpacked_dir/`
3. 如果验证失败：
   - 仔细查看错误信息
   - 修正 XML 中的问题
   - 再次运行验证
4. **仅当验证通过后才继续**
5. 重建: `python scripts/pack.py unpacked_dir/ output.docx`

6.3 计划-验证-执行模式

适用于批量操作、破坏性变更、高风险操作：

分析 → 创建计划文件(changes.json) → 验证计划 → 执行 → 验证结果

好处：

• 在执行前捕获错误
• 机器可验证
• 可逆的计划（不触碰原始文件）
• 清晰的调试路径

七、常见模式与模板

7.1 模板模式

## 报告结构

始终使用此模板：

\`\`\`markdown
# [分析标题]

## 执行摘要
[关键发现的一段式概述]

## 关键发现
- 发现 1 及支撑数据
- 发现 2 及支撑数据

## 建议
1. 具体可执行的建议
2. 具体可执行的建议
\`\`\`

7.2 示例模式

提供输入/输出对，比描述更清晰：

## 提交信息格式

**示例 1：**
输入：添加了 JWT 用户认证
输出：feat(auth): 实现基于 JWT 的认证

**示例 2：**
输入：修复了报告中日期显示错误
输出：fix(reports): 修正时区转换中的日期格式

7.3 条件工作流模式

## 文档修改

1. 判断修改类型：
   **创建新内容？** → 走"创建工作流"
   **编辑现有内容？** → 走"编辑工作流"

2. 创建工作流：...
3. 编辑工作流：...

八、脚本与代码最佳实践

8.1 解决问题，不推卸

脚本应自己处理错误，而非甩给 Claude：

# 正确：显式处理错误
def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"文件 {path} 不存在，创建默认文件")
        with open(path, "w") as f:
            f.write("")
        return ""

# 错误：甩给 Claude
def process_file(path):
    return open(path).read()  # 直接崩溃

8.2 避免魔法数字

# 正确：自解释
REQUEST_TIMEOUT = 30  # HTTP 请求通常在 30 秒内完成
MAX_RETRIES = 3       # 3 次重试在可靠性和速度间取平衡

# 错误：为什么是这个数？
TIMEOUT = 47
RETRIES = 5

8.3 提供工具脚本

预制脚本优于让 Claude 临时生成：

• 更可靠
• 节省 Token（无需在上下文中包含代码）
• 节省时间
• 确保一致性

8.4 明确脚本用途

# 让 Claude 执行（常见）
运行 `analyze_form.py` 提取表单字段

# 让 Claude 作为参考阅读（复杂逻辑）
参见 `analyze_form.py` 了解字段提取算法

九、测试与迭代

9.1 评估驱动开发

先建评估，再写文档。

1. 识别差距：在没有 Skill 的情况下让 Claude 执行任务，记录失败点
2. 创建评估：构建 3 个测试场景
3. 建立基线：测量无 Skill 时的表现
4. 编写最少指令：仅解决差距的内容
5. 迭代：执行评估 → 对比基线 → 改进

9.2 双 Claude 迭代法

Claude A（设计师）          Claude B（测试者）
    │                          │
    ├── 创建/改进 Skill ──────→ │
    │                          ├── 在真实任务中使用
    │                          ├── 观察行为和问题
    │ ←── 反馈问题 ────────────┤
    ├── 根据反馈改进            │
    ├── 更新 Skill ───────────→│
    │                          ├── 再次测试
    ...                        ...

9.3 调试三大常见问题

9.4 观察 Claude 如何导航你的 Skill

迭代 Skill 时，关注 Claude 的实际使用行为，有 4 个关键观察信号：

基于观察迭代，而非基于假设。name 和 description 是最关键的——Claude 靠它们决定是否触发。

9.5 跨模型测试

十、反模式清单

10.1 结构反模式

10.2 内容反模式

10.3 权限反模式

# 反模式：过度授权
allowed-tools: "Bash,Read,Write,Edit,Glob,Grep,WebSearch,Task,Agent"

# 正确：最小权限
allowed-tools: "Bash(git status:*),Bash(git diff:*),Read"

十一、Skill 命名规范

推荐使用动名词形式（gerund）

# 推荐（动名词形式，清晰描述活动）
processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

# 可接受（名词短语或动作导向）
pdf-processing
process-pdfs

# 避免
helper          # 太模糊
utils           # 太通用
documents       # 不描述行为

十二、分发与部署

十三、面向 AEO 的 Skill 优化技巧

来源：微信公众号「奇点漫游者」/ 虎嗅

在 Agent 互联网时代，Skill 不仅要对 Claude 好用，还要让所有 AI Agent 都能发现、理解、信任并调用你的 Skill。以下是面向 AEO（Agent Engine Optimization）的四大优化特质：

13.1 自带 SOP 封装

不是只扔一个接口地址，而是交付带着工具的数字员工。

## 支付处理 SOP

1. 第一步：核对用户余额
2. 第二步：检查风控状态
3. 第三步：发起支付请求
4. 如果遇到风控拦截：
   - 向用户解释原因
   - 建议替代支付方式
   - 记录异常日志

关键：像带徒弟一样，把”老兵经验”写进 SKILL.md。

13.2 设定”反向提示词”（负面边界）

明确告诉 Agent 什么时候不要调用你，反而会极大增加信任评分。

description: >
  处理大额跨境支付（100美元以上）。支持 SWIFT 和 SEPA 网络。
  不要用于：100美元以下的小额支付、国内转账、加密货币交易。

## 不适用场景

以下情况请不要调用本 Skill：
- 小额支付（<100 USD）→ 建议使用 `small-payment` Skill
- 国内银行转账 → 建议使用 `domestic-transfer` Skill
- 需要即时到账 → SWIFT 通常需要 1-3 个工作日

原理：明确边界 → 降低 Agent 出错率 → 提升信任评分 → 关键时刻更多调用。

13.3 具备”自愈能力”（柔性反馈机制）

参数错误时不要直接中断，而是返回结构化的修正指令：

## 错误处理规范

当参数缺失或错误时，返回以下格式的修正指令：

\`\`\`json
{
  "status": "error",
  "error_type": "missing_parameter",
  "missing": "delivery_address",
  "suggestion": "请向用户追问配送地址",
  "example": "请提供您的配送地址（包含城市、区/县、详细地址）"
}
\`\`\`

不要返回空洞的 404 或 500 错误。
每个错误都应包含 suggestion 字段，帮助 Agent 自我纠偏。

对比：

• 平庸 Skill：{"error": 500, "message": "Internal Server Error"} → 任务中断
• 优秀 Skill：{"error": "missing_address", "suggestion": "请向用户追问配送地址"} → Agent 自我纠偏，任务闭环

13.4 原子化与跨平台互通

## 兼容性声明

本 Skill 遵循开放标准，支持以下平台：
- Claude Code / Claude.ai / Claude API
- OpenClaw 本地节点
- ChatGPT Agent（通过适配层）
- 任何支持 Markdown 指令注入的 Agent 框架

## 原子化设计

本 Skill 仅负责「跨境支付」这一个原子化能力。
不包含用户认证、余额查询、汇率转换等功能。
如需这些能力，请组合使用：
- `user-auth` Skill
- `balance-check` Skill
- `currency-exchange` Skill

一处编写，全网运行——像插入 SD 卡一样，瞬间获得能力。

13.5 AEO 三大基本准则在 Skill 中的体现

十四、完整 Checklist

核心质量

• Description 具体，包含关键触发词
• Description 包含「做什么」+「何时用」，使用第三人称
• SKILL.md 正文 < 500 行
• 额外细节拆分到独立文件
• 无时效性信息
• 全文术语一致
• 示例具体，非抽象
• 文件引用仅一层深度
• 恰当使用渐进式披露
• 工作流步骤清晰
• 从模板复制的段落在当前 skill 中确实被引用（无死代码）

代码与脚本

• 脚本自己处理错误，不推卸给 Claude
• 无魔法数字（所有值有注释说明）
• 依赖包已列出并验证可用
• 脚本有清晰文档
• 全部使用正斜杠路径
• 关键操作有验证/验证步骤
• 质量关键任务有反馈闭环

AEO 优化

• 包含反向提示词（负面边界）
• 错误处理返回结构化修正指令（自愈能力）
• 工作流包含完整 SOP（老兵经验）
• 原子化设计，职责单一
• 跨平台兼容性声明

测试

• 至少 3 个评估场景
• 跨模型测试（Haiku/Sonnet/Opus）
• 真实使用场景测试
• 已收集团队反馈

参考来源

• The Complete Guide to Building Skills for Claude — Anthropic 官方 33 页 PDF
• Skill authoring best practices — Anthropic 官方文档
• Anthropic 官方 Skills GitHub 仓库
• Claude Code Skills 文档（中文）
• Claude Agent Skills: A First Principles Deep Dive — Lee Han Chung
• Anthropic’s 33-Page Guide Distilled — 5 Design Patterns — SmartScope
• Anthropic 官方 PDF 指南 Markdown 转换版 — GitHub Gist
• 万字整理：Anthropic 官方 Claude Skills 构建指南 — 知乎
• GEO已死，AEO是答案 — 奇点漫游者/虎嗅