基于 Anthropic 官方 32 页手册
快速导航
章节
内容
适用人群
核心概念
Skills 是什么、三级结构、设计原则
所有读者
规划设计
场景识别、结构设计、指令编写
开发者、高级用户
测试迭代
触发测试、功能测试、A/B 对比
开发者
分发分享
打包发布、文档维护
团队负责人
实战模式
独立 Skills vs Skills+MCP
架构师
故障排查
常见错误、性能优化
所有读者
核心概念
Skills 是什么
一个 Skill 就是一个文件夹：
my-skill/
├── SKILL.md # 必需：核心指令
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
└── assets/ # 可选：模板、字体、图标
三级渐进式设计
级别
位置
内容
目的
1
frontmatter
name/description/category
最小 token，精准触发
2
正文
工作流、步骤、约束
完整执行逻辑
3
references/
API 文档、代码模板
按需加载细节
为什么这样做？
不用三级结构：
每次加载 15,000 tokens，响应慢、成本高
用三级结构：
frontmatter 200 tokens，正文 1,500 tokens，references 按需加载
核心设计原则
原则
说明
示例
渐进式披露
信息分层，按需加载
frontmatter 轻量，references 重型
可组合性
Skills 可互相调用
code-review skill 调用 security-scan skill
可移植性
跨环境使用
.claude/ skills 可在 Claude.ai 和 Claude Code 共享
Skills vs MCP
维度
Skills
MCP
作用
知识层：教 Claude 如何思考和执行
连接层：连接外部数据源和工具
适用
复杂工作流、领域知识、推理流程
API 调用、数据库查询、文件系统
部署
本地或打包分发
需要 MCP 服务器
协同
Skills 可调用 MCP tools
MCP 为 Skills 提供数据和工具
规划与设计
适用场景判断
适合用 Skills：
场景
原因
重复性工作流
一次编写，重复使用
需要领域知识
封装专业方法论
多步骤流程
编排复杂任务
团队协作
标准化 Claude 使用
不适合用 Skills：
场景
替代方案
简单单次任务
直接提示
需要实时数据
用 MCP
超大型项目
拆分成多个 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 三要素：
要素
说明
示例
做什么
核心功能
"Analyzes CSV files up to 10MB"
何时用
触发条件
"Use when user uploads .csv"
不做什么
边界限定
"Doesn't handle Excel files"
常见问题：
问题
❌ 错误写法
✅ 正确写法
过于宽泛
"Helps with data"
"Analyzes CSV files, generates statistics"
缺少触发词
"A code reviewer"
"Reviews code. Use for 'review', 'audit', 'check PR'"
没有边界
"Handles all tasks"
"Manages ProjectHub projects and tasks only"
测试与迭代
三层测试策略
层级
测试内容
方法
工具
1. 触发测试
Skill 是否在正确时机加载
手工测试用例
skill-creator
2. 功能测试
输出是否符合预期
边界案例、错误处理
API 自动化
3. 性能测试
Token 使用、响应时间
A/B 对比
基线测试
触发测试
测试用例模板：
测试：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
用 Skill
改进
来回消息数
15
2
87% ↓
Token 消耗
12,000
6,000
50% ↓
API 失败
3 次
0 次
100% ↓
时间成本
10 分钟
2 分钟
80% ↓
优化技巧
触发器调优
过度触发： 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
文档清单
文档
必需
内容
README.md
✅
简介、安装、使用示例
SKILL.md
✅
Skill 核心文件
CHANGELOG.md
✅
版本历史
LICENSE
可选
开源协议
实战模式
独立 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
故障排查
常见错误
错误
原因
解决方案
Skill 不触发
description 太模糊
添加具体触发词
输出不一致
指令有歧义
明确步骤和约束
Token 超限
references 太大
移到 scripts/ 动态加载
依赖缺失
MCP 未连接
检查 MCP 服务器状态
调试技巧
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 字段
字段
类型
必需
说明
name
string
✅
Skill 唯一标识
description
string
✅
功能描述 + 触发条件
category
string
❌
分类：development/productivity/writing
version
string
❌
版本号：semver
author
string
❌
作者信息
最佳实践清单
发布前检查：
- [ ] 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