CLAUDE.md 每次对话都加载，适合通用规范。但有些知识只在特定场景才用——「如何创建新 API endpoint」、「公司 Git 提交规范」、「支付系统约束」。
把这些都塞进 CLAUDE.md：浪费上下文，让 Claude 分心。
Skills（技能） 是解法：按需加载的专项知识。
Skills vs CLAUDE.md
| CLAUDE.md | Skills | |
|---|---|---|
| 加载时机 | 每次对话 | 按需加载 |
| 适合内容 | 通用规范、架构决策 | 专项知识、可复用工作流 |
| 上下文消耗 | 每次消耗 | 只在相关时消耗 |
| 调用 | 自动 | 自动 + 手动 /name |
目录结构
your-project/
.claude/
skills/
api-conventions/
SKILL.md
fix-issue/
SKILL.md
security-check/
SKILL.md
类型 1：领域知识 Skill
让 Claude 在处理相关代码时自动遵守约束：
markdown
---
name: api-conventions
description: REST API design conventions for our services
---
# API 规范
- URL 路径用 kebab-case
- JSON 字段用 camelCase
- 列表接口必须有分页
- API 路径带版本号（/v1/, /v2/）
- 错误响应：{ error: string, code: number, details?: object }
- 新接口在 Swagger 里更新文档类型 2：工作流 Skill（可手动触发）
markdown
---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true
---
Analyze and fix GitHub issue: ARGUMENTS_VAR
1. `gh issue view ARGUMENTS_VAR` 获取详情
2. 理解问题，搜索相关代码
3. 实现修复，写测试验证
4. 通过 lint 和 type check
5. 写清楚的 commit message，push 并创建 PR用法：/fix-issue 1234
Claude 按 5 步自动完成，从读 issue 到创建 PR。
disable-model-invocation: true：有副作用的 Skill 必须手动触发，防止自动运行。
类型 3：安全检查 Skill
markdown
---
name: security-check
description: Security review checklist
---
# 安全审查清单
- SQL 注入：所有查询用参数化，不拼接字符串
- XSS：用户输入在输出前 escape
- 认证：敏感接口是否有权限检查
- 日志：不能记录密码、token、卡号等敏感信息
- 依赖：新引入的第三方包是否可信
发现问题列出具体文件行号和修复建议。使用：/security-check 检查一下我刚写的用户注册接口
类型 4：支付领域知识 Skill
markdown
---
name: payment-domain
description: Payment processing constraints
---
# 支付系统须知
- 所有金额用分（整数），不用浮点数
- 每笔交易必须有幂等 Key，防止重复扣款
- 退款必须保留完整 audit trail
- PCI DSS：不能在日志里记录卡号任何部分
- WebHook 需要验签，否则有安全风险
- 退款流程异步，不要同步等待团队共享
bash
git add .claude/skills/
git commit -m "add team skills: api-conventions, fix-issue, security-check"新成员克隆仓库就能用所有技能，不需要手动配置。
全局 Skill（所有项目通用）
~/.claude/skills/
git-conventions/
SKILL.md # 个人 Git 提交习惯
code-review/
SKILL.md # 个人 review 检查清单
Skills vs 子 Agent 选哪个？
| 场景 | Skills | 子 Agent |
|---|---|---|
| 注入领域知识 | ✅ | ❌ |
| 复用工作流 | ✅ | ❌ |
| 大范围代码搜索 | ❌ | ✅ |
| 独立上下文验证 | ❌ | ✅ |
来源：Claude Code Best Practices | Claude Code Skills 文档 | 整理：ClaudeEagle