Appearance
Claude Code Skills实战指南：从创建到高级技巧的完整教程
Skills的核心价值：一次教学，终身复用。把重复指令变成可复用模板，团队统一代码风格，Skill按需加载不浪费token，新人加入时Skill就是最佳实践文档。
问题场景
第一次："Claude，帮我写一个FastAPI的CRUD接口"
第二次："Claude，帮我写另一个CRUD接口"（重复相同指令）
第十次："又是CRUD接口..."（你已经厌倦重复了）
Skills解决方案：第一次创建Skill教Claude如何写CRUD接口，之后每次直接调用。
Skills vs 其他定制方式
| 方式 | 用途 | 持久性 | 共享性 |
|---|---|---|---|
| CLAUDE.md | 项目级配置 | 项目内持久 | Git共享 |
| Skills | 可复用的任务模板 | 跨项目持久 | 可发布共享 |
| Hooks | 确定性事件响应 | 本地持久 | 配置文件 |
| Subagents | 任务委托 | 本地持久 | 配置文件 |
选择建议：
- 需要配置项目背景？→ CLAUDE.md
- 需要定义可复用任务？→ Skills
- 需要自动化事件响应？→ Hooks
- 需要委托专门任务？→ Subagents
创建你的第一个Skill
Skill目录结构
skills/
└── crud-generator/
├── SKILL.md # 元数据和触发描述（必需）
├── instructions.md # 详细指令（可选）
├── templates/ # 模板文件（可选）
│ └── crud_template.py
└── scripts/ # 执行脚本（可选）
└── validate.pySKILL.md基本格式
yaml
name: crud-generator
description: |
生成 FastAPI CRUD 接口代码。
当用户需要创建数据库的增删改查接口时触发。
触发词：CRUD、增删改查、REST API。
priority: 10
allowed-tools:
- read
- write
- bash
---
# CRUD Generator Skill
## 什么时候使用
当用户说：
- "创建一个 XXX 的 CRUD 接口"
- "帮我写一个 XXX 的 REST API"
- "XXX 需要增删改查功能"
## 工作流程
1. 确认模型定义（如果不存在，先创建）
2. 生成以下文件：
- routers/{model}.py - 路由文件
- schemas/{model}.py - Pydantic 模型
- services/{model}.py - 业务逻辑
3. 在 main.py 中注册路由
4. 运行测试验证
## 代码规范
参考 templates/crud_template.py 中的代码风格：
- 使用异步函数
- 完整的类型注解
- 统一的错误处理
- 分页查询支持
## 示例输出
参考 references/example_output.md。关键配置详解
1. name（必需）
Skill的唯一标识符，用于命令行调用：
bash
claude --skill crud-generator2. description（必需）
最重要的配置，决定Skill何时被触发。
✅ 好的描述：
yaml
description: |
生成 FastAPI CRUD 接口代码。
触发条件：
- 用户提到 "CRUD"、"增删改查"、"REST API"
- 用户需要创建数据库接口
不触发的情况：
- 用户只想查询数据（不是创建接口）
- 用户在讨论其他框架（不是 FastAPI）❌ 差的描述：
yaml
description: 帮助用户太模糊，无法判断何时触发。
3. priority（可选）
当多个Skills都匹配时，优先级高的先执行。
| 优先级 | 用途 |
|---|---|
| 50+ | 核心Skill |
| 20-40 | 辅助Skill |
| 10 | 通用Skill（默认） |
4. allowed-tools（可选）
限制Skill能使用的工具，提高安全性：
yaml
allowed-tools:
- read # 允许读取文件
- write # 允许写入文件
# 不包含 bash，则 Skill 不能执行命令渐进式信息揭示
避免把所有指令都塞进SKILL.md，采用三层渐进揭示策略：
Level 1: SKILL.md（触发层）
yaml
name: api-doc-generator
description: 生成 API 文档。触发词：API 文档、接口文档、Swagger。
---
## 什么时候使用
[简要说明]
## 工作流程
1. 扫描 API 路由
2. 提取类型信息
3. 生成文档
4. 更新 README
详细指令请参考 instructions.md。Level 2: instructions.md（详细层）
markdown
# API 文档生成详细指令
## 扫描阶段
使用以下命令找到所有路由文件：
find src/api -name "*.py" -type f
对于每个文件，提取：
- 路由路径（@router.get/post/put/delete）
- 请求参数（通过类型注解）
- 响应模型（response_model）
## 文档格式
...Level 3: templates/（模板层）
templates/
├── api_doc_template.md
└── swagger_template.yaml好处：
- 节省上下文：Claude只在需要时读取详细内容
- 维护方便：修改模板不影响触发逻辑
- 模块化：不同类型任务用不同模板
Scripts：执行而不消耗上下文
Scripts是Skill的"延伸手臂"，可以在不消耗Claude上下文的情况下执行复杂操作。
适用场景：代码格式化、静态检查、测试运行、数据转换
python
# scripts/quality_check.py
import subprocess
import sys
def run_checks(file_path: str) -> dict:
"""运行代码质量检查"""
results = {
"black": check_format(file_path),
"isort": check_imports(file_path),
"mypy": check_types(file_path),
"pytest": run_tests(file_path)
}
return results
def check_format(file_path: str) -> bool:
result = subprocess.run(
["black", "--check", file_path],
capture_output=True
)
return result.returncode == 0
if __name__ == "__main__":
file_path = sys.argv[1]
results = run_checks(file_path)
print(results)在SKILL.md中调用：
markdown
## 代码质量验证
生成代码后，运行质量检查：
python scripts/quality_check.py $FILE_PATH
根据检查结果：
- 如果全部通过，继续下一步
- 如果有失败，修复问题后重新检查Skills共享与分发
1. 团队内共享（Git）
bash
# 在项目根目录创建 skills 目录
mkdir -p skills/crud-generator
# 添加到 Git
git add skills/
git commit -m "添加 CRUD 生成器 Skill"
git push
# 团队成员拉取后自动可用
git pull2. 组织级分发（Enterprise Settings）
json
{
"skills": {
"directories": [
"/shared/skills", // 共享 Skills 目录
"~/.claude/skills" // 用户个人 Skills
]
}
}3. 公开发布（ClawHub）
bash
# 安装 ClawHub CLI
npm install -g clawhub
# 发布 Skill
cd skills/crud-generator
clawhub publish
# 其他人安装
clawhub install crud-generator高级技巧
Skills与Subagents结合
把Skill的逻辑封装成Subagent，在独立上下文中执行：
yaml
# .claude/agents/crud-generator.yaml
name: crud-generator
description: 专门生成 CRUD 接口的子代理
system_prompt: |
你是 FastAPI CRUD 接口生成专家。
工作流程：
1. 读取 Skill 配置
2. 分析模型定义
3. 生成代码
4. 运行质量检查
详细指令见：skills/crud-generator/instructions.md
allowed-tools:
- read
- write
- bash动态参数处理
markdown
## 参数说明
调用此 Skill 时，可以指定：
- model: 模型名称（必需）
- auth: 是否需要认证（默认：true）
- pagination: 是否支持分页（默认：true）
示例：
- "创建用户的 CRUD 接口" → model=user
- "创建公开的博客接口，不需要认证" → model=blog, auth=false条件执行
根据项目类型选择不同模板：
markdown
## 模板选择
检查项目类型：
- 如果存在 main.py 且使用 FastAPI → 使用 FastAPI 模板
- 如果存在 app.py 且使用 Flask → 使用 Flask 模板
- 如果存在 settings.py 且使用 Django → 使用 Django 模板故障排除
| 问题 | 检查方法 |
|---|---|
| Skill不触发 | 描述是否匹配？claude --list-skills 查看；优先级是否正确？目录是否在搜索路径？ |
| 多个Skill冲突 | 调整priority，更高的优先执行 |
| 运行时错误 | claude --skill crud-generator --debug 单独测试；查看~/.claude/logs/skill-execution.log |
实战案例：API版本迁移Skill
yaml
name: api-version-migrator
description: |
将 API 从一个版本迁移到另一个版本。
触发词：API 迁移、版本升级、v1 转 v2。
priority: 30
allowed-tools:
- read
- write
- bash
- grep
---
# API Version Migrator
## 功能
将现有 API 迁移到新版本，保持向后兼容。
## 工作流程
1. 分析现有 API
找到所有 v1 路由：grep -r "router = APIRouter" src/api/v1/
2. 创建新版本目录：mkdir -p src/api/v2
3. 迁移代码（复制→更新前缀→应用破坏性变更→更新文档）
4. 添加版本切换：
app.include_router(v1_router, prefix="/api/v1")
app.include_router(v2_router, prefix="/api/v2")
5. 更新客户端（参考 scripts/update_client.py）
详细指令见 instructions.md。总结
Skills的四大核心价值：
| 价值 | 说明 |
|---|---|
| 知识复用 | 一次教学，终身受益 |
| 团队一致 | 统一的代码风格和最佳实践 |
| 上下文高效 | 按需加载，不浪费token |
| 易于分享 | Git或ClawHub一键分发 |
下一步：为你的团队创建第一个Skill，把常用操作封装起来，发布到ClawHub让更多人受益。
