Skills 的团队分发机制
High Contrast
Dark Mode
Light Mode
Sepia
Forest
4 min read793 words

Skills 的团队分发机制

当团队有多个代码仓库，但想共享同一套 Skills 库时，需要一个分发策略。本节对比三种主要方案的优劣，帮你根据团队规模和协作方式选择最合适的分发机制。

三种分发方案对比

方案 适合场景 优点 缺点
方案一：Skills 直接放在项目仓库 单一项目，Skills 高度专属 最简单，无额外依赖 Skills 只能用于一个项目
方案二：独立 Skills 仓库 + 脚本安装 多项目共享通用 Skills 一处维护，多处使用 需要手动同步，可能版本不一致
方案三：Git Submodule 严格版本控制，需要 pin 版本 精确控制每个项目用哪个版本 操作相对复杂，submodule 学习成本

方案一：Skills 直接在项目仓库（最简单）

my-api-project/
├── .claude/
│   ├── skills/          ← Skills 和项目代码在一起
│   ├── settings.json
│   └── CLAUDE.md （在根目录）
└── src/

适合谁：单个项目、初始阶段、Skills 高度依赖项目上下文的情况。

开始使用：

mkdir -p .claude/skills
# 直接创建 Skill 文件，纳入版本控制
git add .claude/
git commit -m "chore: add Claude Code Skills configuration"

方案二：独立 Skills 仓库 + 安装脚本（推荐多项目共享）

仓库结构

company-claude-skills/              ← 独立的 Skills 仓库
├── skills/
│   ├── README.md
│   ├── code-review/
│   ├── docs/
│   └── ops/
├── settings.json.template          ← 权限配置模板
├── CLAUDE.md.template              ← CLAUDE.md 模板
└── install.sh                      ← 安装脚本

安装脚本（install.sh）

#!/bin/bash
# install.sh - 将共享 Skills 安装到当前项目
set -e
SKILLS_REPO="https://github.com/your-company/company-claude-skills.git"
SKILLS_DIR=".claude/skills/shared"
TEMP_DIR=$(mktemp -d)
echo "🔧 安装 Company Claude Skills..."
# 下载最新版本
git clone --depth 1 "$SKILLS_REPO" "$TEMP_DIR" 2>/dev/null
# 创建目标目录
mkdir -p "$SKILLS_DIR"
# 复制 Skills 文件
cp -r "$TEMP_DIR/skills/"* "$SKILLS_DIR/"
# 可选：合并 settings.json
if [ -f ".claude/settings.json" ]; then
echo "⚠️  .claude/settings.json 已存在，请手动合并权限配置"
echo "    参考：$TEMP_DIR/settings.json.template"
else
cp "$TEMP_DIR/settings.json.template" ".claude/settings.json"
echo "✅ 已创建 .claude/settings.json"
fi
# 清理临时目录
rm -rf "$TEMP_DIR"
echo "✅ Company Claude Skills 安装完成"
echo "   位置：$SKILLS_DIR/"
echo "   运行 /help 查看所有可用命令"

在各项目中使用：

# 首次安装
bash <(curl -s https://raw.githubusercontent.com/your-company/company-claude-skills/main/install.sh)
# 更新到最新版本
bash <(curl -s https://raw.githubusercontent.com/your-company/company-claude-skills/main/install.sh)

目录结构（安装后）

my-api-project/
├── .claude/
│   ├── skills/
│   │   ├── shared/                  ← 来自共享仓库的 Skills
│   │   │   ├── code-review/
│   │   │   │   └── review-pr.md     → /review-pr
│   │   │   └── docs/
│   │   │       └── gen-pr-desc.md   → /gen-pr-desc
│   │   └── project-specific/        ← 本项目专有的 Skills
│   │       └── check-migration.md   → /check-migration

方案三：Git Submodule（严格版本控制）

适合需要精确控制"每个项目用共享 Skills 的哪个版本"的团队：

# 添加 Skills 仓库作为 submodule
git submodule add https://github.com/your-company/company-claude-skills.git \
.claude/skills-shared
# 将 submodule 的内容链接到 .claude/skills/ 目录
# 注意：Claude Code 读取的是 .claude/skills/，需要让它能找到 submodule 中的文件
# 创建符号链接（在支持 symlink 的系统上）
ln -s ../skills-shared/skills/code-review .claude/skills/shared-code-review

更新到最新版本：

# 更新 submodule 到最新 commit
git submodule update --remote .claude/skills-shared
git add .claude/skills-shared
git commit -m "chore: update shared Skills to latest version"

Pin 到特定版本：

cd .claude/skills-shared
git checkout v1.2.0   # Pin 到 v1.2.0 版本
cd ../..
git add .claude/skills-shared
git commit -m "chore: pin shared Skills to v1.2.0"

Skills 的发现机制设计

当团队有多套 Skills（项目专有 + 共享）时，如何让成员快速找到所需的 Skill？

策略一：统一 README 索引

在 .claude/skills/README.md 中统一列出所有可用 Skills，无论来源：

# 所有可用 Skills
## 共享 Skills（来自 company-claude-skills）
| 命令 | 来源 | 说明 |
|------|------|------|
| `/review-pr` | shared/code-review/ | 全面 PR 代码审查 |
| `/gen-pr-desc` | shared/docs/ | 自动生成 PR 描述 |
| `/pre-deploy` | shared/ops/ | 部署前检查 |
## 项目专属 Skills（本项目）
| 命令 | 来源 | 说明 |
|------|------|------|
| `/check-migration` | project-specific/ | 数据库迁移检查（支付服务专用）|
| `/test-payment-flow` | project-specific/ | 支付流程端到端测试检查 |

策略二：/skills-help 导航 Skill

创建一个帮助用户发现其他 Skills 的 Skill：

---
description: 列出当前项目所有可用 Skills 及其用法
allowed-tools: Read, Glob
---
# Skills 导航助手
## 目标
列出所有可用的 Skills 及其简短说明，帮助用户快速找到所需的工具。
## 执行步骤
1. 使用 Glob 工具找到所有 `.claude/skills/**/*.md` 文件（排除 `tests/` 目录）
2. 对每个文件，使用 Read 工具读取 frontmatter 中的 `description` 字段
3. 按目录分组输出
## 输出格式

可用 Skills 列表

代码审查

文档生成

（以此类推）

提示：运行 /help 查看详细说明

跨项目 Skills 同步的最佳实践

  1. 共享 Skills 不放项目专有内容：共享 Skills 的步骤描述应该足够通用，不假设特定的项目结构

  2. 用 CLAUDE.md 补充项目上下文：共享 Skill 通过读取项目的 CLAUDE.md 获取项目特定信息（技术栈、命令、目录结构）

  3. 版本号写在 Skills README 中： ```markdown # Skills 库

    共享 Skills 版本：v1.2.0（2026-03-01 更新） ```

  4. Breaking changes 提前通知：如果共享 Skill 的参数接口发生不兼容变更，在 CHANGELOG 中标注并通知所有使用方项目

本节记录清单

下一章：真实场景 Skills 案例集——概念和规范都讲完了。最后一章是直接可用的 Skill 实现：代码审查、PR 描述、部署检查、日志分析——拿来就能用。