06b - Claude Code Skills 创建教程

第 1 级：元数据（~100 tokens）
  └── name + description → Claude 判断是否相关
第 2 级：完整指令（SKILL.md 正文）
  └── 相关时加载详细指令
第 3 级：辅助资源（按需）
  └── 模板、脚本、参考文档等

my-skill/
├── SKILL.md           # 核心文件（必需）：元数据 + 指令
├── template.md        # 可选：Claude 填充的模板
├── examples/
│   └── sample.md      # 可选：期望输出的示例
├── scripts/
│   └── validate.sh    # 可选：Claude 可执行的脚本
└── reference.md       # 可选：详细参考文档

## 附加资源
 
- 完整 API 文档见 [reference.md](reference.md)
- 使用示例见 [examples/sample.md](examples/sample.md)
- 验证脚本：`scripts/validate.sh`

---
name: my-skill
description: What this skill does and when to use it
argument-hint: "[issue-number]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Bash(npm *)
model: sonnet
context: fork
agent: Explore
hooks:
  # Skill 生命周期 hooks
---

---
name: api-conventions
description: API design patterns for this codebase
---
 
编写 API 端点时：
- 使用 RESTful 命名规范
- 返回一致的错误格式
- 包含请求验证

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
 
部署应用到生产环境：
1. 运行测试套件
2. 构建应用
3. 推送到部署目标

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
 
## PR 上下文
- PR diff: !`gh pr diff`
- PR 评论: !`gh pr view --comments`
- 变更文件: !`gh pr diff --name-only`
 
## 你的任务
总结这个 PR 的变更...

---
name: code-reviewer
description: Review code for best practices and security issues
---

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

---
name: legacy-system-context
description: Context about the legacy billing system architecture
user-invocable: false
---

---
name: safe-reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
 
深入研究 $ARGUMENTS：
 
1. 使用 Glob 和 Grep 查找相关文件
2. 阅读并分析代码
3. 总结发现，附带具体文件引用

# 项目级 Skill
mkdir -p .claude/skills/my-skill
 
# 个人级 Skill
mkdir -p ~/.claude/skills/my-skill

cat > .claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Description of what this skill does
---
 
# 指令内容
...
EOF

> 有哪些可用的 skills？

请帮我调试 Skill [skill-name]：
1. 检查 SKILL.md 的 frontmatter 格式是否正确
2. 验证 description 是否清晰描述了触发条件
3. 确认所有引用的辅助文件路径正确
4. 用 [测试 prompt] 测试是否能正确触发

.claude/skills/code-reviewer/
├── SKILL.md
├── checklist.md
└── report-template.md

---
name: code-reviewer
description: Review code for best practices, security issues, and performance in our Next.js + TypeScript + Prisma project. Use when reviewing PRs, analyzing code quality, or before merging.
allowed-tools: Read, Grep, Glob, Bash(git diff *)
---
 
# 代码审查指令
 
## 技术栈上下文
- Next.js 14 App Router
- TypeScript strict mode
- Prisma ORM + PostgreSQL
- Tailwind CSS
- Vitest + Playwright 测试
 
## 审查流程
 
1. **获取变更范围**：使用 `git diff` 或 Grep 确定变更文件
2. **逐文件审查**：按 [checklist.md](checklist.md) 逐项检查
3. **生成报告**：按 [report-template.md](report-template.md) 格式输出
 
## 审查重点
 
### 类型安全
- 禁止 `any` 类型（除非有充分理由并注释）
- 所有函数参数和返回值必须有类型注解
- 使用 Zod 进行运行时验证
 
### API 路由安全
- 所有 API 路由必须有输入验证
- 检查认证和授权中间件
- 错误响应不泄露内部信息
 
### 数据库查询
- 检查 N+1 查询（使用 `include` 而非循环查询）
- 事务操作使用 `$transaction`
- 大数据量查询使用分页
 
### 测试覆盖
- 新功能必须有对应单元测试
- API 路由必须有集成测试
- 关键路径必须有 E2E 测试
 
## 输出格式
 
按严重程度分类：
- 🔴 **必须修复**：安全漏洞、数据丢失风险、类型错误
- 🟡 **建议修复**：性能问题、代码规范违反
- 🟢 **可选优化**：代码风格、可读性改进
- ✅ **做得好的地方**：值得肯定的实践

# 代码审查清单
 
## 必查项
- [ ] 无 `any` 类型
- [ ] API 路由有输入验证
- [ ] 敏感操作有认证检查
- [ ] 无硬编码密钥或凭证
- [ ] 错误处理完整（try-catch + 用户友好错误信息）
 
## 性能项
- [ ] 无 N+1 数据库查询
- [ ] 大列表使用虚拟滚动或分页
- [ ] 图片使用 next/image 优化
- [ ] 无不必要的客户端状态
 
## 测试项
- [ ] 新功能有单元测试
- [ ] API 变更有集成测试
- [ ] 测试覆盖率不低于现有水平

# 代码审查报告
 
## 概要
- 审查范围：[文件数量] 个文件，[行数] 行变更
- 总体评价：[优秀/良好/需改进/需重写]
 
## 🔴 必须修复
1. [文件:行号] 问题描述 → 建议修复方案
 
## 🟡 建议修复
1. [文件:行号] 问题描述 → 建议修复方案
 
## 🟢 可选优化
1. [文件:行号] 优化建议
 
## ✅ 做得好的地方
1. [具体描述]

# 自动触发：Claude 在你请求代码审查时自动加载
> 审查一下最近的代码变更
 
# 手动触发
> /code-reviewer
 
# 带参数
> /code-reviewer src/app/api/

.claude/skills/smart-commit/
├── SKILL.md
└── scripts/
    └── pre-commit-check.sh

---
name: smart-commit
description: Create a well-formatted git commit with conventional commit format. Use when committing code changes.
disable-model-invocation: true
allowed-tools: Read, Bash(git *), Bash(npm run lint *), Bash(npm test *)
argument-hint: "[commit-type] [optional-scope]"
---
 
# 智能提交指令
 
## 提交流程
 
### 第 1 步：分析变更
```bash
git diff --staged --stat
git diff --staged

bash .claude/skills/smart-commit/scripts/pre-commit-check.sh

<type>(<scope>): <description>

<body>

<footer>

git commit -m "<生成的提交信息>"

feat(api): add user authentication endpoint

Implement JWT-based authentication with refresh token support.
This enables secure API access for the mobile app client.

Closes #42

### scripts/pre-commit-check.sh

```bash
#!/bin/bash
# 预提交检查脚本

echo "🔍 运行预提交检查..."

# 检查是否有 staged 文件
STAGED=$(git diff --staged --name-only)
if [ -z "$STAGED" ]; then
  echo "❌ 没有 staged 文件。请先 git add。"
  exit 1
fi

# 运行 lint（如果有配置）
if [ -f "package.json" ] && grep -q '"lint"' package.json; then
  echo "📝 运行 lint..."
  npm run lint --silent 2>&1 || echo "⚠️ Lint 发现问题"
fi

# 检查是否有调试代码
echo "🔎 检查调试代码..."
DEBUGS=$(git diff --staged | grep -n "console\.log\|debugger\|TODO\|FIXME\|HACK" || true)
if [ -n "$DEBUGS" ]; then
  echo "⚠️ 发现可能的调试代码："
  echo "$DEBUGS"
fi

echo "✅ 预提交检查完成"

# 仅手动触发（disable-model-invocation: true）
> /smart-commit
> /smart-commit feat
> /smart-commit fix auth

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

---
name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python *)
---
 
# 代码库可视化
 
生成交互式 HTML 树状视图，展示项目文件结构和代码分布。
 
## 使用方法
 
从项目根目录运行：
 
```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

> 这个示例展示了 Skills 的脚本执行能力——通过 `allowed-tools: Bash(python *)` 授权 Claude 运行 Python 脚本，生成可视化输出。脚本使用 Python 标准库，无需安装额外依赖。完整的 `visualize.py` 脚本可参考 [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code/skills)。

---

## 10. 高级模式与技巧

### Skill 组合

虽然 Skills 不能显式引用其他 Skills，但 Claude 可以自动组合多个 Skills。例如：

- 用户请求"审查代码并提交"
- Claude 先加载 `code-reviewer` Skill 执行审查
- 审查通过后加载 `smart-commit` Skill 生成提交

这种隐式组合是 Skills 最强大的特性之一。

### Hooks 集成

Skills 可以在 frontmatter 中定义生命周期 hooks，在特定事件时自动执行命令：

```yaml
---
name: auto-format
description: Auto-format code on save
hooks:
  PreToolUse:
    - matcher: Write
      command: "npx prettier --write $FILE"
---

请帮我创建一个 Claude Code Skill：
- 用途：[具体任务描述]
- 触发方式：[自动/手动/仅 Claude]
- 需要的工具权限：[Read/Edit/Bash 等]
- 是否需要子代理执行：[是/否]
- 是否需要辅助文件：[模板/脚本/参考文档]

请生成完整的 SKILL.md 和所有辅助文件。

.claude/skills/
├── code-reviewer/        # 代码审查（自动触发）
├── smart-commit/         # 智能提交（手动触发）
├── db-migration/         # 数据库迁移（手动触发）
├── api-generator/        # API 路由生成（手动触发）
├── project-context/      # 项目上下文（仅 Claude 触发）
└── test-generator/       # 测试生成（自动触发）

---
name: project-context
description: Context about our SaaS project architecture, tech stack, and conventions
user-invocable: false
---
 
# 项目上下文
 
## 技术栈
- Next.js 14 App Router + TypeScript 5.x
- Prisma ORM + PostgreSQL 16
- NextAuth.js v5 认证
- Tailwind CSS + shadcn/ui
- Vitest 单元测试 + Playwright E2E
 
## 目录结构约定
- `src/app/` — 页面和 API 路由
- `src/components/` — React 组件
- `src/lib/` — 工具函数和配置
- `prisma/` — 数据库 schema 和迁移
- `tests/` — E2E 测试
 
## 编码规范
- 组件使用函数式 + hooks
- 服务端操作使用 Server Actions
- 所有 API 输入使用 Zod 验证
- 错误处理使用自定义 AppError 类

git add .claude/skills/
git commit -m "chore: add team skills for code review, commit, and project context"
git push