Claude Agent Skills 完全指南

基于 Anthropic 官方 32 页手册

快速导航

核心概念

Skills 是什么

一个 Skill 就是一个文件夹：

my-skill/
├── SKILL.md          # 必需：核心指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、字体、图标

三级渐进式设计

为什么这样做？

不用三级结构：
每次加载 15,000 tokens，响应慢、成本高

用三级结构：
frontmatter 200 tokens，正文 1,500 tokens，references 按需加载

核心设计原则

Skills vs MCP

规划与设计

适用场景判断

适合用 Skills：

不适合用 Skills：

Skill 结构设计

最小可行 Skill：

# SKILL.md
---
name: code-review
description: Reviews code changes. Use when user says "review code", "check PR", or "audit changes".
category: development
---

Review the provided code changes:
1. Check for security issues
2. Verify logic correctness
3. Suggest improvements

完整 Skill 结构：

advanced-skill/
├── SKILL.md              # frontmatter + 工作流
├── references/
│   ├── api-guide.md      # API 文档
│   ├── examples.md       # 示例
│   └── troubleshooting.md # 故障排查
├── scripts/
│   ├── validator.py      # 验证逻辑
│   └── formatter.py      # 格式化输出
└── assets/
    └── template.yaml     # 配置模板

编写有效指令

description 三要素：

常见问题：

测试与迭代

三层测试策略

触发测试

测试用例模板：

测试：ProjectHub Skill 触发

应该触发：
✅ "Create a new project"
✅ "Initialize ProjectHub workspace"
✅ "Add tasks to project"

不应该触发：
❌ "What's the weather?"
❌ "Help me write Python"
❌ "Create a spreadsheet"

功能测试

测试套件结构：

## 基本功能
- 测试 1：创建项目 → 项目已创建
- 测试 2：添加任务 → 任务已添加

## 边界情况
- 边界 1：空项目名称 → 返回错误
- 边界 2：超过任务限制 → 提示升级

## 错误处理
- 错误 1：API 失败 → 重试 3 次
- 错误 2：权限不足 → 提示联系管理员

性能对比

基线对比模板：

优化技巧

触发器调优

过度触发： Skill 加载太频繁
– 收集误触发案例
– 在 description 中添加更具体的约束
– 添加否定条件

不足触发： Skill 应加载但没加载
– 收集漏触发案例
– 添加更多触发短语
– 在 description 中明确使用场景

性能优化

Token 使用：
– 把详细内容移到 references/
– 保持 frontmatter 简洁
– 使用渐进式披露

响应速度：
– 优化脚本性能
– 缓存重复计算
– 批量处理请求

分发与分享

打包 Skill

# 方式 1：直接分享文件夹
zip -r my-skill.zip my-skill/

# 方式 2：发布到 GitHub
git init
git add SKILL.md references/ scripts/
git commit -m "Add my-skill"
git push origin main

文档清单

实战模式

独立 Skills

适用场景：
– 代码审查
– 文档生成
– 数据分析

目录结构：

~/.claude/skills/
├── code-review/
├── doc-writer/
└── data-analyzer/

Skills + MCP 融合

架构：

用户请求
    ↓
Claude 加载 Skill
    ↓
Skill 调用 MCP 工具
    ↓
MCP 返回数据
    ↓
Skill 处理并输出

示例：ProjectHub Skill

# SKILL.md
---
name: projecthub
description: Manages projects in ProjectHub. Requires ProjectHub MCP server.
category: productivity
---

When user wants to create/manage projects:
1. Use projecthub_list_projects to check existing
2. Use projecthub_create_project to create new
3. Use projecthub_add_task to add tasks

故障排查

常见错误

调试技巧

1. 检查 Skill 是否加载：

在 SKILL.md 开头添加：
## Debug
This skill was loaded. Respond with "✅ [skill-name] loaded"

2. 验证 MCP 连接：

# scripts/test_mcp.py
import subprocess
result = subprocess.run(['claude', 'mcp', 'list'], capture_output=True)
print(result.stdout)

3. Token 使用分析：

# 查看 Skill 的 token 消耗
claude skill analyze --name my-skill

快速上手

15 分钟构建第一个 Skill

Step 1：创建目录

mkdir -p ~/.claude/skills/my-first-skill

Step 2：编写 SKILL.md

---
name: my-first-skill
description: Summarizes text into bullet points. Use when user says "summarize", "bullet points", or "key takeaways".
category: productivity
---

Convert the provided text into bullet points:
- Extract key information
- Keep items concise
- Maximum 5 bullets

Step 3：测试

# 在 Claude 中触发
"Summarize this article: [paste text]"

Step 4：迭代
– 收集失败案例
– 优化 description
– 添加 references/

附录

frontmatter 字段

最佳实践清单

发布前检查：
– [ ] description 包含”做什么”和”何时用”
– [ ] 正文有明确步骤，不是泛泛而谈
– [ ] 通过触发测试（不误触、不漏触）
– [ ] 通过功能测试（边界案例覆盖）
– [ ] Token 使用合理（< 3,000 per use）
– [ ] 有 README 和使用示例
– [ ] 版本号已更新

总结

Skills 让你教 Claude 一次，每次都受益。

记住三点：
1. 三级结构：frontmatter → 正文 → references，渐进式披露
2. 明确触发：description 要说清楚做什么、何时用、不做什么
3. 持续测试：触发、功能、性能三层测试

下一步：
– 从小任务开始，15 分钟构建第一个 Skill
– 使用 skill-creator 加速迭代
– 加入社区分享你的 Skills

文档版本：v1.0
基于 Anthropic 官方手册：The Complete Guide to Building Skills for Claude
更新日期：2026-04-15