先说结论
把团队规范沉淀进 Claude Code，最稳的办法不是发一份会被遗忘的文档，也不是靠每个人本机各自配一份，而是写成 .claude/skills/ 下的 skill 并提交到仓库。新人一 clone 就继承，规范跟着代码版本走，改一处全员生效，谁漏装都不会跑偏。个人级目录和插件市场适合“我自己用”或“跨很多仓库分发”，但凡是团队共识，就放进项目仓库。下面是基于官方文档和 anthropics/skills 仓库核实过的落地方式（以下数据为 2026-09-26 从 GitHub API 拉取，该仓库约 17.8 万 star，是 Agent Skills 的官方示例库）。
技能放哪：三种位置，三套边界
Claude Code 找 skill 的位置有三种，作用范围和优先级都不同。文档原文写得很直白：项目级 skill 要“Commit it so your team gets it too”，也就是提交进仓库，团队才能都用上；而用户级目录是“本机所有项目”，属于个人环境，不随仓库走。
| 位置 | 路径 | 生效范围 | 优先级 |
|---|---|---|---|
| 项目级 | .claude/skills/<name>/SKILL.md | 本仓库的会话，提交后团队继承 | 最低 |
| 用户级 | ~/.claude/skills/<name>/SKILL.md | 本机所有项目，不含云/CT 会话 | 高于项目级 |
| 插件市场 | <plugin>/skills/<name>/SKILL.md | 启用插件处，命令形如 /plugin:skill | 命名空间隔离，不覆盖 |
| 企业级 | 由组织下发 | 组织内 | 最高 |
“Enterprise over personal, and personal over project. With deploy in both ~/.claude/skills/ and the project’s .claude/skills/, /deploy runs the personal one.”
这条优先级是团队踩坑的重灾区。如果你在仓库里写了一个 code-review，但某同事本机 ~/.claude/skills/ 也有同名 skill，他跑 /code-review 用的是自己那份，不是团队的——模型按“个人 > 项目”选了本机的。所以团队规范一定要进仓库，且命名要带前缀（比如 team-code-review）避免和个人技能撞车。monorepo 里还能用嵌套目录 <subdir>/.claude/skills/<name>/SKILL.md，只对那个子目录下的会话生效，方便不同子项目各自维护评审口径而不互相干扰。这也是仓库级 skill 比个人目录更适合当团队事实来源的原因：规范写在 git 历史里，谁改的、为什么改都可追溯，出问题能回滚到上一个能用的版本，而不是在某个人本机悄悄漂移。
团队落地：把规范写进仓库
一个典型的落地仓库结构如下，规范、脚本、参考文档各归其位，SKILL.md 只写主干，细节拆到 references/ 和 scripts/，符合“渐进式加载”的原则：
team-repo/
├── .claude/
│ ├── skills/
│ │ ├── code-review/
│ │ │ ├── SKILL.md
│ │ │ └── references/checklist.md
│ │ ├── commit-msg/
│ │ │ └── SKILL.md
│ │ └── release-flow/
│ │ ├── SKILL.md
│ │ └── scripts/tag.py
│ └── settings.json
├── CHANGELOG.md
└── src/
跨多个仓库分发时，走插件市场更省事。在仓库加 .claude-plugin/plugin.json 后即可作为插件加载，命令形如 /my-plugin:review；也可直接引用官方市场：
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
哪些规范适合做成 skill，哪些不适合
| 适合做成 skill | 不适合做成 skill |
|---|---|
| 代码评审口径（命名、分层、异常处理） | 每周都在变的业务规则、促销逻辑 |
| 提交信息规范（类型、长度、语气） | 强依赖实时数据库/线上状态的判断 |
| 发布流程（打 tag、写变更日志、校验） | 需要凭据且会写外部系统的操作 |
| 测试用例写法（边界、mock、覆盖标准） | 一次性的临时脚本 |
判断标准就一句话：skill 是“离线装进上下文的方法论”，它应该在相当长时间内稳定。代码评审和提交规范几个月不变，非常适合；但促销规则、灰度开关、实时库存这些会动的东西写死进去，等于把过期知识当真理。需要实时数据或写外部系统的，留给 MCP（见第 68 篇），别硬塞进 SKILL.md。另外，那种“只有某个人今天要用一次”的临时脚本，做成 skill 反而是污染仓库，放着本地跑完即弃更好。
一个能直接抄的 SKILL.md
这是 code-review 的示例，字段严格按 Agent Skills 规范：name 与目录同名、小写加连字符；description 既要说能干什么，也要说“什么时候用”，并带上关键词帮模型识别触发。规范对 name 限制为 64 字符内、仅小写字母数字与连字符；description 限制 1024 字符内。
---
name: code-review
description: 在提交前做代码评审，检查命名、分层、异常处理与测试覆盖。当用户说“帮我 review”“检查改动”“CR 一下”时使用。
license: Apache-2.0
metadata:
version: "1.2"
---
# 代码评审流程
1. 读 references/checklist.md 的评审清单。
2. 逐文件比对本次 diff，不评无关文件。
3. 给出问题清单，按“必须改 / 建议改”分级。
详见 references/checklist.md。
规范原文对 description 的要求：“Should include specific keywords that help agents identify relevant tasks.”
评审、版本化、避免互相打架
skill 也是代码，要走和源码一样的流程。开 PR、两人评审、合并即生效；用 CHANGELOG 记录每次改动，版本号写在 frontmatter 的 metadata.version 里，方便别人知道现在跑的是哪版。一个最小 CHANGELOG：
## 1.2 - 2026-09-20
- 评审清单新增“空 catch 块”检查项
## 1.1 - 2026-08-02
- 提交信息规范补充 body 长度上限
写完用官方校验工具过一遍格式，能提前拦掉大部分字段写错：
skills-ref validate ./team-repo/.claude/skills/code-review
避免互相打架的要点：第一，团队 skill 统一加 team- 前缀，避开个人目录的同名覆盖；第二，别用保留名 synced 和 anthropic-skills，Claude Code 不会加载这两个名字的目录；第三，职责切分清楚，一个 skill 只管一件事，别让两个 skill 的 description 描述同一句话。反模式清单：
- 把会变的业务规则写死进 SKILL.md，结果规范过期还被当真理。
- 技能命名不带前缀，和个人
~/.claude/skills/撞名，个人级悄悄覆盖团队级。 - 用保留名
synced或anthropic-skills当目录名，加载器直接跳过。 - 一个
description堆十几条关键词想“总被触发”，实际是到处乱触发（见第 67 篇）。 - 把 skill 当私有脚本藏本地不提交，规范只在某个人脑子里。
下一步怎么做
先挑一条最稳的规范（比如提交信息）做成第一个 skill 提交仓库，跑两周看大家是否真在用；再逐步把评审、发布流程搬进来。多人协作的团队该做，solo 开发者把它们放 ~/.claude/skills/ 就够了，不必为单仓库强上插件市场。如果某成员坚持用自己的个人版覆盖团队规范，说明这条规范还没达成共识，先回到 PR 讨论把它定清楚再写进仓库——skill 只是载体，共识才是前提。规范一旦定型，它就是团队最便宜的“新人培训”和“代码守门员”。