转载请注明出处❤️

作者：测试蔡坨坨

原文链接：caituotuo.top/c4e91a6b.html

0. 前言

你好，我是测试蔡坨坨。

最近在整理项目里的 Skills，像是在翻一个很久没有收拾过的工具箱。乍一看什么都有，真正要用的时候才发现，这把锤子放在这里，那把螺丝刀又跑到了另一边。

刚开始为了图省事，哪个 AI 工具需要，就往对应目录放一份：.agents/skills、.claude/skills、.codex/skills。当时觉得这样最直接，也确实都能正常工作。

但随着 Skills 越来越多，问题也慢慢出现了。修改了一个 Skill，另外两份要不要同步？到底哪一份才是最新的？某个工具读的又是哪一份？时间一长，维护成本反而越来越高。

后来我把这些 Skills 重新整理了一遍，只保留一份真正的原件，其他目录全部通过软链接（Symbolic Link）指向它。

这样无论是 Claude Code、Codex，还是其他支持 Skills 的 AI Coding 工具，看到的都是同一份内容。修改一次，所有工具立即生效，也更适合同一批 Skills 在多个项目之间复用。

这篇文章就分享一下我是怎么整理的，以及为什么我越来越推荐这种方式。

1. 尽量不用用户级别 Skill

Skill 可以理解成给 AI Agent 的工作说明书。

写文章有写文章的规则，做接口测试有测试流程。不同项目需要的能力并不一样，因此我不太建议把所有 Skills 都放到用户级别目录，也就是所谓的全局 Skill。

全局 Skill 看起来很方便，所有项目都能直接使用，但实际维护起来很容易失控。博客项目根本用不到接口测试 Skill，自动化测试项目也不需要公众号排版规则。随着 Skills 越积越多，每个项目都会看到一大堆与自己无关的能力。

更重要的是，它还会带来上下文污染。

大多数 AI Agent 工具虽然不会在启动时一次性读取所有 SKILL.md，但通常都会先扫描 Skill 的名称和描述，再决定是否加载对应内容。一旦判断某个 Skill 与当前任务有关，就会把更多规则加入上下文。

无关的 Skill 越多，误匹配的概率就越高，不仅会增加上下文消耗，还可能让 Agent 选择错误的 Skill，导致回答越来越偏离当前项目。

所以我的原则一直很简单：项目需要什么，就只让项目看到什么。

我更倾向于只使用项目级 Skills。比如这个博客项目，就只保留写作、文本润色、资料抓取等相关 Skills；接口测试、代码审查、数据库分析这些能力完全不放进来。等以后真正需要的时候再添加，也比一开始把所有工具都塞进去更容易维护。

2. 只保留一份原件

Skills 最怕的就是复制多份。

今天，.agents/skills 放一套，明天 .claude/skills 放一套，后天 .codex/skills 又放一套。刚开始一切正常，等你修了一个脚本、改了一条规则，就开始犯迷糊：我刚才改的是哪一份？为什么这个工具还是旧效果？

所以在一个项目里，我只保留一个 Skills 入口：

1

.agents/skills/

真正的 Skill 都放在这里。比如：

1
2
3
4
5
6
7
8

.agents/skills/
├── ctt-article-write/
│   ├── SKILL.md
│   └── scripts/
│       ├── x_article_fetcher.py
│       └── wechat_article_fetcher.py
└── Humanizer-zh/
    └── SKILL.md

以后无论是修改写作规则、修复抓取脚本，还是补充参考资料，都只改 .agents/skills 这一份。项目里始终只有一个入口，也只有一份原件，维护起来不会混乱。

如果多个项目都需要复用同一个 Skill，还可以再往前走一步：把自己维护或开源的 Skills 放到一个统一仓库，再让各个项目通过软链接引用它。

1
2
3
4
5

~/GitHub/agent-skills/skills/article-write

project-a/.agents/skills/article-write -> ~/GitHub/agent-skills/skills/article-write

project-b/.agents/skills/article-write -> ~/GitHub/agent-skills/skills/article-write

这样，每个项目依然只认 .agents/skills 这个入口，不需要关心 Skill 实际放在哪里；而真正需要维护的原件，也始终只有 ~/GitHub/agent-skills 里的一份。

改一次，所有项目同步生效，再也不用在几份几乎一样的目录之间来回复制和同步。

3. 其它入口全部用软链接

有些 AI Coding 工具默认会到 .claude/skills、.codex/skills 等目录下寻找 Skills。这种情况下，我不会再复制一份，而是直接用软链接把它们指向 .agents/skills。

例如，对于 Claude Code：

1

ln -s ../.agents/skills .claude/skills

创建完成后，可以检查一下：

1

readlink .claude/skills

如果输出：

1

../.agents/skills

就说明 .claude/skills 只是一个入口，真正的内容依然来自 .agents/skills。

对于 .codex/skills 也是一样。

因为 Codex 也支持原生读取 .agents/skills 目录，所以我会直接删掉整个 .codex 目录：

1

rm -rf .codex

这样，无论是 Claude Code、Codex，还是其他 AI Coding 工具，最终访问的都是同一份 Skills。

整个项目始终只有一个真正需要维护的目录，其余位置都只是不同工具的入口。

我的原则一直只有一句话：入口可以有很多个，原件永远只有一份。

4. 命令不用自己记

其实，软链接命令记不住也没关系，这类重复性的操作本来就很适合交给 Agent。

比如直接告诉它：

1

帮我把 ~/GitHub/agent-skills/skills/article-write 链接到当前项目的 .agents/skills/article-write。

或者更简单一点：

1

把当前项目的 .claude/skills 改成指向 .agents/skills 的软链接。

一般情况下，Agent 都能完成这些操作。

不过我的习惯是，让它按固定流程执行，而不是上来就修改文件。

首先用 ls -la 查看当前目录结构，确认已有内容；如果需要替换已有目录，再先说明影响并征得确认；完成之后，再用 readlink 验证软链接是否正确，必要时再配合 find 检查整个 Skills 目录。

这样做的好处是，每一步都有检查，出了问题也容易定位。

尤其是已经维护了一段时间的项目，更不要让 Agent 一上来就 rm -rf。先确认，再修改，最后验证，永远比直接动手更稳妥。

5. 一个原则，长期受益

初次整理整套目录，确实会多花几分钟，但之后会轻松很多。

第一，更新只改一处。比如抓取脚本修了一个 Bug，只需要修改原件，所有通过软链接引用它的项目都会自动用上新版本。

第二，修复可以反哺原件。你在某个项目里发现 Skill 有问题，让 Agent 修的时候，修改的就是统一仓库里的那一份。提交一次，所有项目都能同步收益，不需要再逐个同步。

现在管理 Skills 的原则只有一句话：

项目级配置，只保留一个源头，其它工具入口全部使用软链接。

这套方法并不复杂，却能避免很多低级问题。以后无论是修脚本、改规则，还是补文档，都知道应该修改哪一份。

AI 工具越多，这个优势就越明显。先把 Skills 管理好，再让 AI 帮你干活，而不是让自己先陷入一堆重复维护和配置同步里。