跨项目技能共享的三层轻量方案

来源：X @petergyang

一位开发者分享的做法是：在项目的 Claude.md 中写一行 The shared repo instructions live in: @AGENTS.md，在 Agents.md 中写 Canonical user skills live in ~/.claude/skills，这样跨项目通用的指令和技能就有了统一去处 ^[0]。作者自称这套方案 “kinda messy but solves the problem” ^[0]。它乱在哪里、又为什么能解决问题，取决于 Claude Code 加载技能的底层机制。

同时维护多个项目的开发者，通常要为每个代码库设置各自的代码风格、测试规范和部署流程。每个项目都独立维护一套完整指令，会造成配置冗余，提高维护成本 ^[0]。加载方式是成本高的具体原因：CLAUDE.md 在每次会话开始时被加载 ^[2,5]，且全量常驻在上下文里 ^[6]。项目越多，被重复加载的常驻内容就越多。

这套方案将“项目配置”和“通用内容”分为三层。

第一层是入口，项目的 CLAUDE.md 只保留一行路由，内容为 The shared repo instructions live in: @AGENTS.md ^[0]。@ 前缀是 Claude Code 引用文件或目录的语法，通过自动补全将目标文件拉入上下文 ^[3,30]。素材第一节把这行误标为 AGENTS.md 的内容——按推文原文，它写在 Claude.md 里 ^[0]。

第二层是索引，AGENTS.md 指明内容位置，只有一行：Canonical user skills live in ~/.claude/skills ^[0]。选择 AGENTS.md 而非直接写路径，是因为它与 CLAUDE.md 角色相同，但 Codex CLI、Copilot 等工具识别的是它，多工具团队常以它作为规范来源 ^[39]。路由经过它，等于顺带将这份索引暴露给其他工具。

第三层是内容，~/.claude/skills 是 Claude Code 的全局技能目录，跨所有项目可用 ^[2,10,39,41]。每个技能是一个文件夹，内含带 YAML frontmatter（name、description 必填）的 SKILL.md ^[9,10]；文件夹名同时成为斜杠命令 ^[2]，description 用于模型自动发现并判断何时触发 ^[5,6]。

方案自称“低侵入性、零脚本”，轻量的来源不是文件引用链，而是 Claude Code 的两套加载语义。

其一，CLAUDE.md 全量常驻 ^[6]，所以路由必须极薄——只有一行，没有多余内容 ^[0]。

其二，技能是两级加载：启动时只预载 frontmatter 元数据（name、description），完整内容在用户调用或模型触发时才读取 ^[1]。各家对单个技能元数据的估算在约 30–50 token ^[59]、约 100 token ^[50]、约占上下文预算 2% ^[6] 之间，量级一致：每个技能只付元数据的成本。因此全局目录可以堆几十上百个技能而不撑爆上下文——每次会话只有被触发的 1–2 个技能被载入 ^[40,59]。模型依靠 description 自动判断是否加载某个技能 ^[5,9,52]。

结合起来看：将共享指令复制进每个项目的 CLAUDE.md，代价是常驻 token 乘以项目数；放进全局技能目录，代价只有一份元数据。这是方案“轻”的机理。

目录位置必须选对。Claude Code 的全局技能目录是 ~/.claude/skills，不是通用 agent 的规范位置 ~/.agents/skills。技能装进后者，Claude Code 读不到，这是一个已被报告的 bug ^[7]。

多工具团队可以更进一步。SKILL.md 是开放格式，可以把共享技能目录用符号链接挂到各 agent 的预期路径（.claude/skills、.agents/skills、.github/skills 等）^[39]。Claude Code 解析技能时会用 realpath() 对符号链接去重，同一份文件不会被当作多个技能 ^[1]。

避免三层重复。同一规则在 CLAUDE.md、AGENTS.md、skill 各写一份，等于制造三个更新点 ^[44]。分层的目的就是各自写各自的：路由只负责指路，内容只在全局目录维护一份。

全局目录要纳入版本控制。否则每台机器各跑一个版本，技能会悄悄漂移，直到你不信任它们 ^[9]。

这套方案是约定而非功能。skill 的触发与执行是“建议性”的——模型是否照做由它自己判断 ^[6]；作者也承认它 “kinda messy” ^[0]。它解决的是“维护一份、处处生效”的问题，代价是接受一层不保证执行的间接引用。

跨项目技能共享的三层轻量方案

参考来源