构建企业级 Skill 库，把个人经验变成团队资产
写在前面
说实话，上一篇我们学会了创建简单的 Skill，解决个人效率问题。
但你可能已经想到更多场景：
场景1：复杂 Skill
一个完整的"代码发布" Skill 需要包含：
- 发布流程说明
- 版本号规范
- 回滚步骤
- 检查清单
- 常见问题处理
全部塞进一个文件？太乱了。
场景2：团队共享
你写了一个很好用的"代码审查" Skill，想分享给团队：
- 直接发文件？太原始
- 放到仓库里？怎么同步更新？
- 不同项目有不同规范怎么办？
场景3：版本管理
Skill 更新了，但旧项目还在用旧版本：
- 如何管理多个版本？
- 如何让不同项目使用不同版本？
这篇文章，我们来解决这些问题。
一、多文件 Skill：模块化组织
1.1 为什么需要多文件？
当一个 Skill 变得复杂时，单文件的问题就暴露出来：
❌ 单文件的问题：
┌────────────────────────────────────────────────────────────┐
│ SKILL.md (2000行) │
│ ├─ 发布流程说明（300行） │
│ ├─ 版本号规范（200行） │
│ ├─ 回滚步骤（400行） │
│ ├─ 检查清单（500行） │
│ └─ 常见问题处理（600行） │
│ │
│ 问题： │
│ • Claude 每次都要读 2000 行 │
│ • 修改一部分要翻很久 │
│ • 团队协作容易冲突 │
└────────────────────────────────────────────────────────────┘
解决方案：拆分成多个文件，按需加载。
1.2 多文件 Skill 结构
deploy/
├── SKILL.md # 主文件（入口）
├── workflow.md # 发布流程
├── versioning.md # 版本号规范
├── rollback.md # 回滚步骤
├── checklist.md # 检查清单
└── troubleshooting.md # 常见问题
1.3 SKILL.md 作为"目录"
主文件只负责引导，不包含具体内容：
---
name: deploy
description: 部署应用到生产环境
disable-model-invocation: true
---
# 部署 Skill
将应用安全地部署到生产环境。
## 执行流程
### 1. 前置检查
详见 [checklist.md](checklist.md)
### 2. 版本号处理
详见 [versioning.md](versioning.md)
### 3. 执行发布
详见 [workflow.md](workflow.md)
### 4. 遇到问题？
详见 [troubleshooting.md](troubleshooting.md)
### 5. 需要回滚？
详见 [rollback.md](rollback.md)
1.4 Claude 如何使用多文件 Skill
┌────────────────────────────────────────────────────────────┐
│ 多文件 Skill 加载流程 │
├────────────────────────────────────────────────────────────┤
│ │
│ 1. 用户调用 /deploy │
│ ↓ │
│ 2. Claude 加载 SKILL.md（主文件） │
│ ↓ │
│ 3. Claude 根据任务判断需要哪些支持文件 │
│ • 需要检查清单？→ 加载 checklist.md │
│ • 需要回滚？→ 加载 rollback.md │
│ • 需要处理问题？→ 加载 troubleshooting.md │
│ ↓ │
│ 4. Claude 只加载需要的文件（节省 token） │
│ │
└────────────────────────────────────────────────────────────┘
关键优势：
- Claude 只读取需要的部分
- 修改某个模块不影响其他
- 团队可以并行编辑不同文件
二、构建企业级 Skill：完整示例
2.1 场景：代码审查 Skill
让我们构建一个完整的代码审查 Skill，涵盖安全、性能、规范等方面。
目录结构：
code-review/
├── SKILL.md # 主文件
├── security/ # 安全检查
│ ├── injection.md # 注入攻击
│ ├── xss.md # 跨站脚本
│ └── auth.md # 认证授权
├── performance/ # 性能检查
│ ├── database.md # 数据库
│ ├── memory.md # 内存
│ └── network.md # 网络
├── style/ # 代码风格
│ ├── naming.md # 命名规范
│ ├── structure.md # 代码结构
│ └── comments.md # 注释规范
└── templates/ # 输出模板
└── report.md # 审查报告模板
2.2 主文件 SKILL.md
---
name: code-review
description: 全面的代码审查，检查安全性、性能和代码规范。当请求代码审查、Code Review 或代码检查时使用。
allowed-tools: Read, Grep, Glob
---
# 代码审查 Skill
对代码变更进行全面的审查，发现潜在问题并提供改进建议。
## 审查范围
### 🔒 安全性
- [SQL 注入](security/injection.md)
- [XSS 攻击](security/xss.md)
- [认证授权](security/auth.md)
### ⚡ 性能
- [数据库查询](performance/database.md)
- [内存管理](performance/memory.md)
- [网络请求](performance/network.md)
### 📝 代码风格
- [命名规范](style/naming.md)
- [代码结构](style/structure.md)
- [注释规范](style/comments.md)
## 输出格式
使用 [审查报告模板](templates/report.md) 输出结果。
## 审查流程
1. **识别变更范围**
- 使用 Grep 找到修改的文件
- 使用 Read 读取变更内容
2. **执行检查**
- 按优先级：安全 > 性能 > 风格
- 每个类别加载对应的检查文件
3. **生成报告**
- 汇总发现的问题
- 按严重程度排序
- 提供具体的修复建议
2.3 安全检查文件示例
security/injection.md：
# SQL 注入检查
## 检查要点
### 1. 字符串拼接 SQL
❌ 危险模式：
```javascript
const query = "SELECT * FROM users WHERE id = " + userId;
✅ 安全模式：
const query = "SELECT * FROM users WHERE id = ?";
db.query(query, [userId]);
2. 动态表名/列名
❌ 危险模式：
const query = `SELECT * FROM ${tableName}`;
✅ 安全模式：
const allowedTables = ['users', 'orders', 'products'];
if (!allowedTables.includes(tableName)) {
throw new Error('Invalid table name');
}
3. ORM 使用
- 检查是否使用 ORM 的安全方法
- 避免 raw query 中的字符串拼接
检测方法
# 搜索可疑模式
grep -rn "SELECT.*+\|INSERT.*+\|UPDATE.*+\|DELETE.*+" --include="*.ts" --include="*.js"
### 2.4 输出模板
**templates/report.md**：
```markdown
# 代码审查报告
## 概要
| 指标 | 数量 |
|------|------|
| 🔴 严重问题 | X 个 |
| 🟠 中等问题 | X 个 |
| 🟡 轻微问题 | X 个 |
| ✅ 通过检查 | X 个 |
## 问题详情
### 🔴 严重问题
#### 1. [问题标题]
- **文件**：`path/to/file.ts:行号`
- **类型**：安全/性能/风格
- **描述**：问题描述
- **建议**：修复建议
- **代码示例**：
```diff
- 原代码
+ 修复后代码
总结
[审查总结和建议]
---
## 三、团队共享：把 Skill 变成团队资产
### 3.1 三种共享方式
┌─────────────────────────────────────────────────────────────────┐
│ Skill 共享方式 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 方式 位置 共享范围 │
│ ──────────────────────────────────────────────────────────────── │
│ │
│ 项目内 .claude/skills/ 项目团队成员 │
│ 提交到 Git 仓库 │
│ │
│ 组织级 企业托管位置 全公司 │
│ 由 IT 管理 │
│ │
│ 插件形式 独立仓库/包 安装插件的项目 │
│ 通过市场分发 │
│ |
└─────────────────────────────────────────────────────────────────┘
### 3.2 项目内共享（推荐起步）
**最简单的方式**：把 `.claude/skills/` 提交到 Git 仓库。
your-project/
├── .claude/
│ └── skills/
│ ├── code-review/ # 团队共享的代码审查 Skill
│ ├── deploy/ # 团队共享的部署 Skill
│ └── api-docs/ # 团队共享的文档生成 Skill
├── src/
└── package.json
**.gitignore 配置**：
```gitignore
# 提交团队共享的 Skill
!.claude/
!.claude/skills/
# 但忽略个人本地配置
.claude/local/
CLAUDE.local.md
3.3 版本控制策略
问题：Skill 更新了，但旧项目需要旧版本怎么办？
方案一：语义化版本
.claude/skills/
├── code-review/
│ ├── v1/ # 旧版本
│ │ └── SKILL.md # name: code-review-v1
│ ├── v2/ # 当前版本
│ │ └── SKILL.md # name: code-review
│ └── SKILL.md # 指向当前版本的符号链接
方案二：Git 分支
main 分支：最新版 Skill
v1.x 分支：兼容旧项目的 Skill 版本
项目选择：
- 新项目：使用 main 分支
- 旧项目：使用 v1.x 分支
方案三：配置文件指定
在项目的 CLAUDE.md 中指定使用的 Skill 版本：
# 项目配置
## 使用的 Skill 版本
- code-review: v2
- deploy: v1
3.4 团队协作流程
┌─────────────────────────────────────────────────────────────────┐
│ Skill 协作流程 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. 提议阶段 │
│ • 创建 Issue 讨论 Skill 需求 │
│ • 确定范围和设计 │
│ │
│ 2. 开发阶段 │
│ • Fork 仓库或创建分支 │
│ • 在 feature 分支开发 │
│ • 本地测试验证 │
│ │
│ 3. 审查阶段 │
│ • 创建 Pull Request │
│ • 团队成员 Code Review │
│ • 讨论和修改 │
│ │
│ 4. 发布阶段 │
│ • 合并到主分支 │
│ • 更新 CHANGELOG │
│ • 通知团队成员 │
│ │
└─────────────────────────────────────────────────────────────────┘
四、符号链接：跨项目共享 Skill
4.1 使用场景
你有多个项目，它们共享一些通用的 Skill：
~/projects/
├── project-a/
├── project-b/
├── project-c/
└── shared-skills/ # 共享的 Skill 仓库
├── code-review/
├── commit/
└── api-docs/
4.2 创建符号链接
Linux/macOS：
# 在项目 A 中链接共享 Skill
ln -s ~/projects/shared-skills/code-review ~/projects/project-a/.claude/skills/code-review
# 在项目 B 中链接共享 Skill
ln -s ~/projects/shared-skills/code-review ~/projects/project-b/.claude/skills/code-review
Windows（管理员权限）：
mklink /D "C:\projects\project-a\.claude\skills\code-review" "C:\projects\shared-skills\code-review"
4.3 符号链接的优势
┌────────────────────────────────────────────────────────────┐
│ 符号链接 vs 复制文件 │
├────────────────────────────────────────────────────────────┤
│ │
│ 复制文件： │
│ • 更新时需要同步所有副本 │
│ • 容易出现版本不一致 │
│ • 维护成本高 │
│ │
│ 符号链接： │
│ • 一处更新，处处生效 │
│ • 始终保持版本一致 │
│ • 维护成本低 │
│ │
│ 注意：Git 默认不跟踪符号链接的内容，只跟踪链接本身 │
│ │
└────────────────────────────────────────────────────────────┘
五、Skill 测试与验证
5.1 为什么需要测试？
Skill 也是代码，需要验证它是否按预期工作。
❌ 常见问题：
- description 写得不清楚，Claude 不触发
- 指令有歧义，Claude 理解错误
- 输出格式不符合预期
- 支持文件路径错误
5.2 测试检查清单
# Skill 测试检查清单
## 基础检查
- [ ] SKILL.md 语法正确（YAML frontmatter 格式）
- [ ] name 字段符合规范（小写、数字、连字符）
- [ ] description 清晰描述了 Skill 用途
- [ ] 支持文件路径正确
## 触发测试
- [ ] 手动调用 `/skill-name` 成功
- [ ] 自动触发：描述匹配时 Claude 使用
- [ ] 参数传递：`/skill-name arg1 arg2` 正确接收
## 内容测试
- [ ] Claude 理解指令并执行正确步骤
- [ ] 输出格式符合预期
- [ ] 错误情况处理得当
## 边界测试
- [ ] 没有参数时行为正确
- [ ] 参数包含特殊字符时处理正确
- [ ] 大文件/大量数据处理能力
5.3 调试技巧
1. 检查 Skill 是否被识别
# 在 Claude Code 中
> 有哪些可用的 Skill？
2. 检查 Skill 加载情况
# 查看当前上下文
> /context
3. 手动触发测试
# 直接调用，避免自动触发的问题
> /skill-name 测试参数
4. 简化问题
# 最小化测试 Skill
---
name: test-skill
description: 测试用的简单 Skill
---
执行测试：
1. 打印收到的参数：$ARGUMENTS
2. 确认 Skill 被正确加载
六、Skill 维护与演进
6.1 版本更新流程
# Skill 更新日志
## v2.1.0 (2024-01-15)
### 新增
- 添加 TypeScript 支持检查
- 新增性能检查模块
### 修改
- 优化 SQL 注入检测规则
- 更新输出报告格式
### 修复
- 修复参数解析问题
## v2.0.0 (2024-01-01)
### 重大变更
- 重构为多文件结构
- 不兼容 v1.x 配置
### 迁移指南
将 .claude/skills/review 改名为 .claude/skills/code-review
6.2 废弃策略
当 Skill 需要废弃时：
---
name: old-skill
description: ⚠️ 已废弃，请使用 new-skill
deprecated: true
replacement: new-skill
---
# 此 Skill 已废弃
请使用 `/new-skill` 替代。
迁移指南：
1. ...
2. ...
6.3 文档维护
每个 Skill 应该有配套的 README：
code-review/
├── SKILL.md
├── README.md # 使用说明
├── CHANGELOG.md # 变更日志
├── security/
├── performance/
└── templates/
README.md 模板：
# 代码审查 Skill
## 功能
- 安全性检查
- 性能检查
- 代码风格检查
## 使用方法
### 自动触发
当你说"帮我审查代码"时自动激活。
### 手动调用
/code-review [文件路径]
## 参数说明
- `文件路径`（可选）：指定要审查的文件或目录
## 输出
生成结构化的审查报告，包含问题详情和修复建议。
## 配置
可以在 CLAUDE.md 中自定义检查规则。
## 更新日志
见 [CHANGELOG.md](CHANGELOG.md)
七、实战案例：团队 Skill 库
7.1 推荐的团队 Skill 库结构
team-skills/ # 团队共享 Skill 仓库
├── README.md # 仓库说明
├── skills/
│ ├── code-review/ # 代码审查
│ ├── commit/ # 提交消息生成
│ ├── deploy/ # 部署助手
│ ├── test-gen/ # 测试生成
│ ├── api-docs/ # API 文档生成
│ └── refactor/ # 重构助手
├── templates/ # 通用模板
│ ├── skill-template/ # 新 Skill 模板
│ └── output-templates/ # 输出格式模板
└── docs/
├── contribution.md # 贡献指南
├── style-guide.md # 写作风格指南
└── best-practices.md # 最佳实践
7.2 贡献指南示例
docs/contribution.md：
# Skill 贡献指南
## 命名规范
### Skill 名称
- 使用小写字母和连字符
- 使用动词-名词结构
- 示例：`code-review`、`gen-docs`、`deploy-app`
### 文件命名
- 主文件：`SKILL.md`
- 支持文件：使用小写和连字符
- 示例：`security-check.md`、`output-template.md`
## 必需内容
### SKILL.md
1. YAML frontmatter（name、description）
2. 功能概述
3. 使用方法
4. 参数说明（如有）
### README.md
1. 详细说明
2. 使用示例
3. 配置选项
4. 已知限制
## 提交前检查
- [ ] Skill 在本地测试通过
- [ ] 文档完整
- [ ] 遵循命名规范
- [ ] 添加了变更日志
7.3 CI/CD 集成
可以在 CI 中验证 Skill 格式：
# .github/workflows/validate-skills.yml
name: Validate Skills
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate SKILL.md files
run: |
for file in $(find . -name "SKILL.md"); do
echo "Validating $file"
# 检查 YAML frontmatter
python scripts/validate-skill.py "$file"
done
- name: Check file structure
run: |
for dir in skills/*/; do
if [ ! -f "$dir/SKILL.md" ]; then
echo "Error: Missing SKILL.md in $dir"
exit 1
fi
done
七、效果验证
学完本篇，你应该能够完成以下任务：
验证清单
- 创建多文件 Skill 结构
- 编写引用其他文件的 SKILL.md
- 使用动态上下文注入（
!command``） - 在子代理中运行 Skill
- 将 Skill 提交到 Git 供团队使用
动手练习（10分钟）
任务：创建一个多文件的「项目健康检查」Skill
health-check/
├── SKILL.md # 主文件
├── security.md # 安全检查项
├── performance.md # 性能检查项
└── style.md # 代码风格检查项
SKILL.md：
---
name: health-check
description: 项目健康检查，包括安全、性能、代码风格
agent: Explore
---
# 项目健康检查
对项目进行全面健康检查。
## 检查维度
### 安全性
详见 [security.md](security.md)
### 性能
详见 [performance.md](performance.md)
### 代码风格
详见 [style.md](style.md)
## 输出格式
生成健康报告：
- 各维度得分（0-100）
- 发现的问题
- 改进建议
测试：
> /health-check
八、总结与下期预告
本文要点
- 多文件结构：复杂 Skill 拆分成模块，按需加载
- 团队共享：提交到 Git、符号链接、组织托管
- 版本管理：语义化版本、Git 分支、配置指定
- 测试验证：检查清单、调试技巧、CI 集成
- 维护演进：变更日志、废弃策略、文档维护
下期预告
下一篇，我们进入 Hooks 实战：
- 什么是 Hook：在工具执行前后插入自定义逻辑
- 事件类型：PreToolUse、PostToolUse、Notification 等
- 安全考虑：防止恶意 Hook，控制执行权限
- 实战案例：自动代码审查、敏感操作拦截
敬请期待！
附录：快速参考
多文件 Skill 结构模板
my-skill/
├── SKILL.md # 主文件（必需，<500行）
├── README.md # 使用说明
├── CHANGELOG.md # 变更日志
├── modules/ # 功能模块
│ ├── module-a.md
│ └── module-b.md
├── templates/ # 输出模板
│ └── output.md
└── scripts/ # 辅助脚本
└── helper.py
团队共享命令速查
# 创建符号链接
ln -s /path/to/shared-skill .claude/skills/skill-name
# 验证 Skill 结构
find .claude/skills -name "SKILL.md" -exec echo "Found: {}" \;
# 检查符号链接
ls -la .claude/skills/
本篇属于 Claude Code 提效系列第 5 篇（进阶篇第 2 篇）
下期预告：Hooks 实战——控制 Claude 的每一个动作
创建时间：2026-02-14
参考文档：Claude Code 中文文档 - Skills
评论区