为 AI Agent 编写高质量 Skill：Claude 官方指南

前言

如果你在用 Claude Code / Cursor / Codex 这类 AI Agent，可能遇到过这些问题：

同样的任务，每次对话结果差异很大
想让 AI "记住" 某些工作流程，但它就是不稳定
多步骤任务经常在中间某个环节出错

Skill（技能） 就是解决这类问题的标准化方案。官方定义：

Skill 是一组打包好的指令，教给 AI 一次，永久受用。与其在每次对话中重复解释偏好和流程，不如通过 Skill 只教一次。

Claude 官方发布了一份 30+ 页的《The Complete Guide to Building Skills》，我翻译整理了中文版，本文先提炼下核心，大家可以速览。

一、Skill 的本质：三层渐进式架构

Skill 不只是一个 Markdown 文件，而是一套渐进式披露（Progressive Disclosure） 机制：

层级	内容	加载时机	作用
第一层	YAML frontmatter	始终加载到 system prompt	让 AI 知道何时使用这个 Skill
第二层	SKILL.md 正文	任务相关时加载	完整的指令和指导
第三层	references/ 目录	按需加载	详细文档、API 参考等

这部分大家估计都很熟悉，快速跳过

二、文件结构规范

bash 复制代码

your-skill-name/
├── SKILL.md              # 必需 - 主文件
├── scripts/              # 可选 - 可执行脚本
│   └── validate.py
├── references/           # 可选 - 详细文档
│   └── api-guide.md
└── assets/               # 可选 - 模板等资源
    └── template.md

硬性规则：

规则	正确 ✅	错误 ❌
文件名	`SKILL.md`	`skill.md` / `SKILL.MD`
文件夹命名	`my-cool-skill`	`My Cool Skill` / `my_cool_skill`
是否包含 README	不要在 Skill 内放 README	README.md 会干扰解析

三、YAML Frontmatter：决定 Skill 能否被触发

这是最关键的部分。如果 frontmatter 写得不好，Skill 永远不会被调用，或者被过度调用。

最小格式

yaml 复制代码

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

Description 的核心公式

css 复制代码

[它做什么] + [何时使用它] + [关键触发短语]

好 vs 差的对比

差的写法：

yaml 复制代码

# ❌ 太模糊，AI 不知道何时用
description: Helps with projects.

# ❌ 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# ❌ 太技术化，没有用户视角
description: Implements the Project entity model with hierarchical relationships.

好的写法：

yaml 复制代码

# ✅ 具体 + 触发短语
description: Analyzes Figma design files and generates developer handoff 
documentation. Use when user uploads .fig files, asks for "design specs", 
"component documentation", or "design-to-code handoff".

# ✅ 动作明确 + 场景清晰
description: Manages Linear project workflows including sprint planning, 
task creation, and status tracking. Use when user mentions "sprint", 
"Linear tasks", "project planning", or asks to "create tickets".

# ✅ 端到端流程 + 用户语言
description: End-to-end customer onboarding workflow for PayFlow. 
Handles account creation, payment setup, and subscription management. 
Use when user says "onboard new customer", "set up subscription", 
or "create PayFlow account".

调试技巧

如果 Skill 不触发，直接问 AI：

"When would you use the [skill-name] skill?"

AI 会引用 description 字段来回答。根据它的回答调整你的 description。

四、三类常见 Skill 模式

类型 1：文档/资产创建

场景：生成一致、高质量的输出（文档、设计稿、代码等）

关键技术：

嵌入式风格指南
模板结构
输出前的质量检查清单

示例：frontend-design skill

markdown 复制代码

## Quality Checklist
Before finalizing output:
- [ ] Typography hierarchy consistent
- [ ] Color palette follows brand guide
- [ ] Responsive breakpoints defined
- [ ] Accessibility contrast ratios met

类型 2：工作流程自动化

场景：多步骤流程，需要一致的方法论

关键技术：

分步工作流 + 验证关卡
常见结构的模板
迭代细化循环

示例：顺序工作流编排

markdown 复制代码

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification
⚠️ If fails: retry with alternate method

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

类型 3：多 MCP 协调

场景：工作流程跨越多个服务

示例：设计到开发交接

markdown 复制代码

### Phase 1: Design Export (Figma MCP)
1. 从 Figma 导出设计资产
2. 生成设计规格
3. 创建资产清单

### Phase 2: Asset Storage (Drive MCP)
1. 在 Drive 中创建项目文件夹
2. 上传所有资产
3. 生成可共享链接

### Phase 3: Task Creation (Linear MCP)
1. 创建开发任务
2. 将资产链接附加到任务
3. 分配给工程团队

### Phase 4: Notification (Slack MCP)
1. 在 #engineering 发布交接摘要
2. 包含资产链接和任务引用

五、指令编写最佳实践

1. 具体且可操作

markdown 复制代码

# ❌ 差
Make sure to validate things properly

# ✅ 好
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

2. 清晰引用资源

markdown 复制代码

在编写查询之前，请查阅 `references/api-patterns.md` 了解：
- 速率限制指导
- 分页模式
- 错误代码和处理

3. 包含错误处理

markdown 复制代码

## Common Issues

### MCP Connection Failed
如果你看到"Connection refused"：
1. 验证 MCP 服务器正在运行
2. 确认 API 密钥有效
3. 尝试重新连接

4. 对抗"懒惰"

markdown 复制代码

## Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

六、常见问题排查

问题 1：Skill 不触发

原因：description 太模糊或缺少触发短语

解决：

添加用户实际会说的关键词
提及相关文件类型（如 .fig、.csv）
用 "When would you use this skill?" 调试

问题 2：Skill 触发太频繁

解决：添加否定触发器

yaml 复制代码

description: Advanced data analysis for CSV files. 
Use for statistical modeling, regression, clustering. 
Do NOT use for simple data exploration (use data-viz skill instead).

问题 3：指令不被遵循

常见原因：

指令太冗长 → 保持简洁，用列表
关键信息被埋没 → 用 ## CRITICAL 标题
语言模糊 → 用代码/脚本替代自然语言

高级技巧：对于关键验证，用脚本而非语言指令

markdown 复制代码

运行 `scripts/validate.py --input {filename}` 检查数据格式

代码是确定性的，语言解释不是。

问题 4：上下文太大，响应变慢

解决：

SKILL.md 保持 5000 字以下
详细文档移到 references/
减少同时启用的 Skill 数量（建议 < 20 个）

七、Checklist

开发阶段

测试阶段

八、我做的工具：Skill Reviewer

读完这份指南后，我基于官方指南生成了一个 自动检查工具 ：github.com/alienzhou/s...

用法：

bash 复制代码

请使用 /skill-reviewer skill 检查 [你的 Skill 路径]

输入你的 Skill 路径
AI 自动按标准检查
输出合规报告 + 改进建议

官方英文原版文档和中文翻译版都放到 github.com/alienzhou/s...

欢迎自取！