团队 Skills 库的目录结构规范

把个人 Skill 变成团队资产的第一步，是建立一套清晰的目录结构规范。规范不是为了限制创造力，而是让团队里的每个人都能快速找到所需的 Skill，并且知道应该把新 Skill 放在哪里。

团队 Skills 库的完整目录结构

.claude/
├── skills/
│   ├── README.md                    ← Skills 库总索引
│   ├── CHANGELOG.md                 ← 变更历史
│   │
│   ├── code-review/                 ← 代码审查类
│   │   ├── review-pr.md             → /review-pr
│   │   ├── security-check.md        → /security-check
│   │   └── performance-check.md     → /performance-check
│   │
│   ├── docs/                        ← 文档生成类
│   │   ├── gen-pr-desc.md           → /gen-pr-desc
│   │   ├── changelog.md             → /changelog
│   │   └── api-docs.md              → /api-docs
│   │
│   ├── ops/                         ← 运维操作类
│   │   ├── pre-deploy.md            → /pre-deploy
│   │   ├── check-migration.md       → /check-migration
│   │   └── rollback-check.md        → /rollback-check
│   │
│   ├── analysis/                    ← 数据与日志分析类
│   │   ├── analyze-logs.md          → /analyze-logs
│   │   ├── perf-report.md           → /perf-report
│   │   └── dependency-check.md      → /dependency-check
│   │
│   ├── onboarding/                  ← 新成员入职辅助类
│   │   ├── codebase-tour.md         → /codebase-tour
│   │   └── setup-check.md           → /setup-check
│   │
│   └── tests/                       ← 测试用例与基线（不是 Skills）
│       ├── baselines/
│       │   ├── review-pr-normal.md
│       │   └── pre-deploy-staging.md
│       └── quality-checklist.md
│
├── settings.json                    ← 项目级权限配置
└── CLAUDE.md                        ← 项目级行为准则（在根目录）

注意：CLAUDE.md 在项目根目录，不在 .claude/ 里。

Skills 分类体系

团队 Skills 建议按以下类别组织：

强制的文件规范

每个 Skill 文件必须包含以下要素（由 quality-checklist.md 强制）：

必须有效的 Frontmatter

---
description: 一句话说明，80 字符以内
allowed-tools: Read, Bash   # 只列出实际需要的工具
---

必须有调用示例

## 参数说明
**调用示例**：

/review-pr # 最简单的用法 /review-pr --branch feature/auth # 指定分支 /review-pr --branch feature/auth --focus security # 指定分支和重点

必须有版本注记（重要变更时）

<!-- 版本：1.2 | 最后修改：2026-03-22 | 修改人：@username -->

README.md 的标准格式

# 项目 Skills 库
> 项目：Payment Processing Service
> 维护：Platform Engineering Team
> 版本：见各文件注记
## 使用说明
所有 Skills 需要 Claude Code CLI v1.0+ 和项目 `.claude/settings.json` 中配置的权限。
## 快速索引
### 代码审查（code-review/）
| 命令 | 说明 | 参数 |
|------|------|------|
| `/review-pr` | 全面 PR 代码审查 | `--branch`（默认当前分支），`--focus security\|performance\|all` |
| `/security-check` | 安全漏洞专项扫描 | `--file <路径>`（可选，默认扫描 src/） |
| `/performance-check` | 性能问题检查 | 无参数 |
### 文档生成（docs/）
| 命令 | 说明 | 参数 |
|------|------|------|
| `/gen-pr-desc` | 自动生成 PR 描述 | 无（读取 git diff） |
| `/changelog` | 生成版本 CHANGELOG | `--version <版本号>` |
| `/api-docs` | 生成 API 接口文档 | `--file <路由文件路径>` |
### 运维操作（ops/）
| 命令 | 说明 | 参数 |
|------|------|------|
| `/pre-deploy` | 部署前检查清单 | `--env staging\|production`（必填） |
| `/check-migration` | 数据库迁移安全检查 | `--migration <文件名>`（可选） |
| `/rollback-check` | 回滚可行性评估 | `--version <版本号>` |
## 贡献新 Skill
1. 在对应功能目录下创建 Skill 文件（命名：`{verb}-{object}.md`）
2. 确保通过 `tests/quality-checklist.md` 的所有必须项
3. 在本 README.md 的索引表中添加新条目
4. 在 `CHANGELOG.md` 记录新增内容
5. 提交 PR，至少需要 1 位 Platform Engineering 团队成员审查
## 已知限制
- 所有 Skills 在项目根目录中运行，确保 `git` 命令能正常执行
- 需要 `GITHUB_TOKEN` 环境变量的 Skills：`/gen-pr-desc`、`/changelog`
- production 环境操作需要额外的权限配置，见 `settings.json`

Skills 的命名冲突处理

如果团队有多个项目都在用 Skills，且有同名 Skill，需要明确区分：

# 项目 A（API 服务）
.claude/skills/review-pr.md    ← /review-pr（专注后端安全检查）
# 项目 B（前端）
.claude/skills/review-pr.md    ← /review-pr（专注 React/CSS 规范）

因为 Skills 在项目级生效，同名 Skill 在不同项目中可以有不同的内容——这是预期行为。

如果一个 Skill 需要被多个项目共享，使用用户级 Skills（~/.claude/skills/），并在命名上添加通用性前缀（避免与项目级 Skill 冲突）：

~/.claude/skills/
├── shared-standup.md        ← /shared-standup（所有项目通用）
└── shared-git-summary.md    ← /shared-git-summary（所有项目通用）

本节记录清单

• [ ] 按照本节的目录结构，整理现有 Skills 到对应类别目录
• [ ] 创建符合标准格式的 .claude/skills/README.md
• [ ] 确认所有 Skill 文件都有 description frontmatter
• [ ] 为团队建立 Skill 命名约定文档

下一节：用 Git 管理 Skills 版本——Skills 在 Git 中的工作流：分支、PR 审查、版本标签，和代码一样管理 Skills 的变更。