在 .claude/skills/ 中组织 Skill
High Contrast
Dark Mode
Light Mode
Sepia
Forest
2 min read417 words

在 .claude/skills/ 中组织 Skill

当一个项目只有 1–2 个 Skill 时，文件放在 .claude/skills/ 根目录就够了。但当 Skills 库增长到 10 个、20 个时，合理的目录结构决定了你能不能找到想用的 Skill，以及新团队成员能不能快速上手。

目录结构的两种模式

模式一：扁平结构（适合 ≤10 个 Skill）

.claude/
└── skills/
├── review-pr.md
├── gen-pr-desc.md
├── pre-deploy.md
├── analyze-logs.md
└── standup.md

优点：简单直接，新增 Skill 不需要决定放哪里。 缺点：超过 10 个 Skill 后，列表混乱，找不到想要的。

模式二：按功能分组（适合 >10 个 Skill）

.claude/
└── skills/
├── 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

优点：按功能归类，易于发现和维护。 缺点：需要维护分组一致性。

命名约定

Skill 文件命名

格式：{动词}-{对象}[-{修饰}].md
✅ 好的命名：
review-pr.md          （动词 + 对象）
gen-pr-desc.md        （缩写 + 对象）
check-migration.md    （动词 + 对象）
analyze-logs-error.md （动词 + 对象 + 修饰）
❌ 差的命名：
code.md              （太模糊）
prReview.md          （驼峰，不符合 CLI 惯例）
my_skill.md          （下划线，约定用连字符）
Skill1.md            （无意义）

参数化 Skill 的命名

如果 Skill 有明显的目标对象，把对象类型体现在名称中：

review-pr.md       → /review-pr --pr 123
review-file.md     → /review-file --file src/auth.ts
deploy-service.md  → /deploy-service --env staging --service api

README.md：Skills 库的索引

在 .claude/skills/ 目录中放置一个 README.md，作为整个 Skills 库的索引：

# 项目 Skills 库
## 快速索引
### 代码审查
| 命令 | 说明 | 示例 |
|------|------|------|
| `/review-pr` | 全面的 PR 代码审查 | `/review-pr --branch feat/auth` |
| `/security-check` | 安全漏洞专项扫描 | `/security-check --file src/api.ts` |
| `/performance-check` | 性能问题检查 | `/performance-check` |
### 文档生成
| 命令 | 说明 | 示例 |
|------|------|------|
| `/gen-pr-desc` | 自动生成 PR 描述 | `/gen-pr-desc` |
| `/changelog` | 生成版本变更日志 | `/changelog --version 2.1.0` |
### 运维操作
| 命令 | 说明 | 示例 |
|------|------|------|
| `/pre-deploy` | 部署前检查清单 | `/pre-deploy --env production` |
| `/check-migration` | 数据库迁移验证 | `/check-migration` |
## 贡献新 Skill
1. 在对应功能目录下创建 `{verb}-{object}.md`
2. 确保 frontmatter 包含 `description` 字段
3. 在本 README.md 的索引表中添加新条目
4. 提交 PR，请求 Tech Lead 审查

.gitignore 配置

Skills 文件通常应该加入版本控制（这是 Skills 优于提示词的核心原因之一）：

# .gitignore 中不要忽略 .claude/skills/
# 可以忽略的是个人临时 Skill（以 _ 开头的文件）
.claude/skills/_*.md
# 可以忽略的是本地调试用的 Skill
.claude/skills/debug-*.md

个人 Skill vs 团队 Skill：

.claude/
└── skills/
├── review-pr.md      ← 团队 Skill，提交到 Git
├── pre-deploy.md     ← 团队 Skill，提交到 Git
└── _my-scratch.md   ← 个人临时 Skill，不提交（被 .gitignore）

初始化 Skills 库的标准流程

# 步骤 1：创建目录
mkdir -p .claude/skills
# 步骤 2：创建 README 索引
cat > .claude/skills/README.md << 'EOF'
# Skills 库
## 索引
（待填写）
## 贡献指南
在对应目录创建 Skill 文件，更新本索引，提交 PR。
EOF
# 步骤 3：创建第一个 Skill（用模板）
cat > .claude/skills/hello-world.md << 'EOF'
---
description: 验证 Skills 系统是否正常工作
allowed-tools: Bash
---
# Hello World
## 目标
这是一个测试 Skill，验证 Skills 系统已正确配置。
## 执行步骤
1. 运行 `echo "Skills 系统正常工作！"`
2. 显示当前工作目录
3. 列出 .claude/skills/ 中的文件
## 输出
显示确认信息和当前 Skills 库的文件列表。
EOF
# 步骤 4：验证 Skill 已注册
# 在 Claude Code 中运行：/hello-world

本节记录清单

下一节：运行第一个 Skill 并验证输出——文件都准备好了，现在实际运行第一个 Skill，看看它是怎么工作的。