TL;DR: 多工具时代, skill 不该各管各的
如果你同时在用 Claude Code、Codex、openclaw、hermes 这类 agent 工具, 大概率已经踩进同一个坑: 同一套”让 agent 怎么提交代码””怎么写 commit message””怎么发布到 WordPress”的知识, 被你在四个工具里各写了一遍。改一处, 另外三处忘了同步; 半年后想不起来哪个版本是最新的; 换台机器又得手动拷一遍。
这不是工具的问题, 是你把 skill 当成了”每个工具的私有配置”, 而不是”独立于工具存在的工程资产”。
一句话结论: agent skill 本质是纯文本 + 脚本目录, 天然适合用 git 管理、用软链或子模块在多工具间共享一份源、用语义化版本号追踪演进。 把这三件事做对, 你维护的就从”四份会漂移的副本”变成”一份可 diff、可回滚、可团队协作的真相源”。
下面按这个顺序拆: 先讲清楚 skill 到底是什么、为什么能跨工具复用; 再给标准化目录结构; 然后是一份源多工具复用的几种接法; 接着是 git 版本管理与变更记录; 最后是跨工具迁移的差异点和团队协作流程。
读之前如果你对 agent 工具本身还没选定, 可以先看 Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 和 Codex vs Cursor 额度对比: 价格、限制与选型建议, 把工具盘子定下来再谈复用更有意义。
一、Agent Skill 的本质: 为什么它能跨工具
1.1 Skill 不是插件, 是”可被加载的专业知识包”
很多人第一次接触 skill, 会下意识把它类比成浏览器插件或者 IDE 扩展——一个绑死在某个宿主里、调一套私有 API 的二进制。这个类比会把你带偏。
以 Claude Code 的 Skill 范式为例, 一个 skill 的核心就是一个文件夹, 里面放一份 SKILL.md。这份 markdown 顶部有 YAML frontmatter, 只需要两个字段就能跑起来:
---
name: commit
description: 用规范化的 conventional commit 信息创建提交。当用户要求提交代码、写 commit message、整理变更时触发。
---
# Commit Skill
## 何时使用
当工作区有未提交改动, 且用户要求"提交""commit""存一下"时。
## 步骤
1. 运行 `git status` 和 `git diff` 看清改了什么
2. 按 conventional commit 规范归类: feat / fix / docs / chore ...
3. 生成简洁的标题 + 必要的正文
4. 提交前用 `git diff --staged` 复核
注意它的形态: 没有一行宿主专属代码, 全是自然语言 + shell 命令。 这正是它能跨工具的根本原因——它描述的是”做这件事的方法”, 而方法本身不依赖某个特定 agent 的运行时。
1.2 渐进式加载: description 是检索入口, 不是装饰
Claude Code 的 skill 有一个关键机制叫渐进式披露 (progressive disclosure): 系统启动时, 并不会把每个 skill 的全文塞进上下文, 而是只加载 name 和 description 两个字段。模型根据当前任务语义匹配到某个 description, 才会去读那份 SKILL.md 的正文; 正文里再引用 references/ 或 scripts/ 时, 又是按需加载。
这套机制对”复用”有两个直接含义:
description写得好不好, 决定了 skill 能不能被正确触发。 它不是文档摘要, 是检索关键词。要把”什么时候用我”写清楚, 把用户可能说的触发词都覆盖到。- 正文和资源按需加载, 意味着一个 skill 可以很厚而不污染上下文。 你可以把长 checklist、模板、参考表都塞进
references/, 平时不占 token, 用到才拉。
这种”薄入口 + 厚实现”的思路, 和 agent 工程里反复出现的一个判断是同构的: 复杂度应该沉淀进可复用的资产, 而不是困在一次性对话里。关于 harness 和 skill 谁轻谁重的取舍, Agent Harness 不是要安装的软件包 和 Loop Engineering 是 Harness 的局部命名 讲得比较透, 值得对照着读。
1.3 为什么”纯文本 + 脚本目录”是可迁移的最大公约数
再看 Codex、openclaw、hermes。它们各自的扩展机制在字段名、加载方式上肯定有差异——Codex 有自己的指令文件与自定义提示约定; openclaw、hermes 这类工具有各自的组织方式。但把它们抽象一层就会发现, 几乎所有 agent 工具的”能力扩展”都落在同一个最大公约数上:
一段告诉 agent 怎么做某件事的自然语言提示, 加上一组它可以调用的脚本/命令。
以 hermes 这类偏调度型的 agent 为例, 它的 skill 通常也是走 prompt 描述 + 脚本目录的组织方式; openclaw 这类工具同理。字段叫什么、放在哪个目录、用什么格式声明触发条件, 这些是表层差异; 而”提示 + 脚本”这个内核是共享的。
这就是跨工具复用在工程上成立的前提: 你维护的真相源应该是这个内核, 而把各工具的表层差异留给一层薄薄的适配。下面所有方法论都建立在这个判断上。
二、标准化目录结构: 一份 skill 长什么样
复用的第一步是约定结构。如果每个 skill 的内部布局都不一样, 后面的软链、迁移、版本管理都无从下手。下面是一套被验证可用的标准布局——它向 Claude Code 的 skill 约定看齐, 同时刻意保持”任何工具都能消费”的中立性:
skills/
├── commit/
│ ├── SKILL.md # 入口: frontmatter(name/description) + 正文
│ ├── references/ # 按需加载的厚资料: 规范表、模板、checklist
│ │ └── conventional-commit-spec.md
│ └── scripts/ # 可执行脚本, 被正文引用
│ └── gen-message.sh
├── blog-publish/
│ ├── SKILL.md
│ ├── references/
│ │ ├── seo-title-rules.md
│ │ └── frontmatter-template.md
│ ├── scripts/
│ │ ├── build-images.py
│ │ └── publish.sh
│ └── assets/ # 静态资源: 模板图、样式片段
│ └── poster-base.svg
└── code-review/
├── SKILL.md
└── references/
└── review-checklist.md
几条约定值得明确:
- 一个 skill 一个目录, 目录名即 skill 名, 和 frontmatter 里的
name保持一致。这样工具扫描目录就能建立索引。 SKILL.md是唯一入口, 正文尽量短, 把”何时用 / 怎么用 / 边界”讲清楚即可。详细规则下沉到references/。scripts/放确定性逻辑。 agent 擅长决策, 不擅长精确执行重复步骤。能用脚本固化的(改文件名、调 API、跑校验), 就别让模型每次现写。这点和”把 agent 当决策者、把确定性留给代码”的工程直觉一致, 构建 Agent 和写软件, 是两种工程 对这个边界有专门的讨论。references/是按需加载区。 越厚越好, 因为平时不占上下文。SEO 清单、品牌规范、API 字段表, 都该放这里。assets/放二进制或静态模板, 和会频繁 diff 的文本分开, 避免污染 git 历史。
这套结构的好处是关注点分离: 决策(SKILL.md)、知识(references)、执行(scripts)、资源(assets)各居其位。换工具时, 你迁移的是整个目录, 而不是从一坨混在一起的配置里抠。
三、一份 skill 源, 多工具复用
结构定了, 接下来是核心问题: 同一个 skill, 怎么让 Claude Code、Codex、openclaw、hermes 都能用上, 而只维护一份源?
核心原则只有一句: 真相源 (source of truth) 唯一, 各工具的目录是它的投影。 不要在每个工具的配置目录里各放一份会各自演化的副本。下面是三种接法, 从轻到重。
3.1 方案 A: 软链接 (symlink)——最轻, 适合单人多工具
把所有 skill 集中放在一个独立仓库, 比如 ~/agent-skills/。然后在每个工具期望的目录位置, 用软链指过去:
# 真相源
~/agent-skills/skills/commit/
~/agent-skills/skills/blog-publish/
# 各工具消费点, 全部软链到同一份源
ln -s ~/agent-skills/skills ~/.claude/skills
ln -s ~/agent-skills/skills ~/.codex/skills
ln -s ~/agent-skills/skills ~/.config/openclaw/skills
改一处, 处处生效, 因为它们物理上就是同一份文件。优点是零同步成本、改完立即可见; 缺点是软链对某些工具的扫描器不一定友好(有的工具不跟随符号链接), 跨机器要重新建链, Windows 下软链权限也更麻烦。
适用场景: 单人、同一台开发机、多个工具。这是收益最高、成本最低的起点。本站把自营分站统一管理时也用过类似”一份源 + 多处指向”的思路。
3.2 方案 B: git submodule——适合多仓库、需要钉版本
如果 skill 要被多个项目仓库引用, 而且你希望每个项目能钉在某个 skill 版本上(不被上游改动随时影响), 用 git submodule:
# 在项目仓库里把 skill 仓库挂为子模块
cd my-project
git submodule add [email protected]:me/agent-skills.git .agent/skills
# 各工具再软链到子模块目录, 或工具直接读这个路径
ln -s ../.agent/skills .claude/skills
# 升级时显式拉取并锁定到新 commit
cd .agent/skills && git pull origin main && cd -
git add .agent/skills && git commit -m "chore: bump skills to latest"
submodule 的关键价值是版本锁定: 子模块在父仓库里记录的是一个确定的 commit hash。这意味着 A 项目可以用 skill 的 v1.2, B 项目还停在 v1.0, 互不干扰, 升级是一次显式的、可在 PR 里 review 的动作。代价是 submodule 的心智负担确实存在(忘记 --recurse-submodules、游离 HEAD 等老问题), 团队得统一约定。
3.3 方案 C: 同步脚本——工具不认软链时的兜底
有些工具就是不跟随软链, 或者要求 skill 必须是真实文件。这时用一个幂等的同步脚本, 把真相源拷贝到各工具目录:
#!/usr/bin/env bash
# sync-skills.sh —— 把真相源同步到各工具消费目录
set -euo pipefail
SRC="$HOME/agent-skills/skills"
for dst in \
"$HOME/.claude/skills" \
"$HOME/.codex/skills" \
"$HOME/.config/openclaw/skills"
do
mkdir -p "$dst"
rsync -a --delete "$SRC/" "$dst/" # --delete 保证目标和源一致, 不留孤儿
echo "synced -> $dst"
done
rsync --delete 保证目标目录和源完全一致, 不会留下已删 skill 的残骸。把这个脚本挂到 git 的 post-merge hook 或一条手动命令上, 每次更新源后跑一次即可。它比软链笨, 但最通用——任何工具都吃真实文件。
三种方案不互斥: 常用工具走软链, 个别挑食的工具用同步脚本补齐, 跨项目引用上 submodule。判断标准就一条——永远只有一份会被编辑的源, 其余都是它的只读投影。 这和”不要重复造轮子、把基础设施收敛成一份”的工程主张是一回事, 告别重复造轮子: 为什么 AI Agent 创业不应自研基础设施 把这个取舍讲到了创业层面。
四、版本管理: 用 git 把 skill 当代码养
skill 是纯文本, 这意味着它能享受软件工程几十年积累的全部版本管理红利。别浪费这个优势。
4.1 skill 仓库本身就该是个 git 仓库
最基本的一步: ~/agent-skills/ 初始化成 git 仓库, 推到远端。这样你立刻获得三件事——历史可追溯(谁在什么时候改了哪条规则)、可回滚(某次改动让 skill 触发变差, 一个 git revert 回去)、可 diff(改动一目了然, 因为全是文本)。
这正是”纯文本 + git”组合的核心价值。对比一下: 如果你的 skill 是埋在某个工具 GUI 里的配置项, 上面这三件事一件都做不到。
4.2 语义化版本: 给 skill 打 tag
当 skill 开始被多个项目、多个人引用时, 引入语义化版本 (SemVer) 就有意义了。约定:
- MAJOR (
2.0.0): 破坏性变更。比如改了 skill 的触发语义、删了某个被脚本依赖的字段、调整了输出格式, 老的调用方需要适配。 - MINOR (
1.3.0): 向后兼容地加能力。新增一个 reference、扩展触发词、加一个可选脚本。 - PATCH (
1.2.1): 修字。typo、措辞优化、修一个脚本 bug, 不改行为契约。
打 tag 的操作:
git tag -a v1.3.0 -m "blog-publish: 新增 SEO 标题硬规则 reference"
git push origin v1.3.0
submodule 引用时, 就可以钉到 v1.3.0 这个 tag 而非游动的 main, 升级变成”从 v1.3.0 到 v1.4.0″这种可读、可评审的动作。
4.3 CHANGELOG: 让”为什么这么改”留痕
git 历史记录了”改了什么”, 但”为什么改、改了之后触发效果有没有变好”需要单独留痕。在 skill 仓库根放一份 CHANGELOG.md:
# Changelog
## [1.3.0] - 2026-06-26
### Added
- blog-publish: 接入 SEO 标题硬规则 reference, 标题生成前强制过清单
### Changed
- commit: description 补充"存一下""归档"等触发词, 提升命中率
## [1.2.1] - 2026-06-20
### Fixed
- code-review: 修正 checklist 里一处误导性表述
这件事在 agent 语境下尤其重要。skill 的好坏不像普通代码那样有确定的单元测试, 它的”对不对”体现在触发是否准、产出是否稳。 你改一版 description, 触发率可能上去也可能下去, 这本质是个需要观测的反馈过程。把每次改动和它的意图记下来, 才能在效果回退时定位是哪一次改坏的。
关于”agent 的效果如何度量”这件事本身就是门学问, LLM 评测的下一步是一张二维矩阵 和 Prompt Learning 的两个反馈圈 提供了两套可以直接借用的视角: 前者讲怎么把评测组织成可读的矩阵, 后者讲提示迭代的反馈闭环, 都能套到”skill 改完怎么验证”上。
五、跨工具迁移: 差异点在哪里, 怎么处理
把内核标准化之后, 真正的工作量在处理各工具的表层差异。这里列出迁移时最常踩的几类差异和应对。
5.1 frontmatter / 元数据格式差异
不同工具对”这个 skill 叫什么、什么时候触发”的声明方式不一定相同。Claude Code 用 SKILL.md 顶部的 YAML frontmatter(name + description); 其他工具可能用别的文件名、别的字段、甚至别的格式。
应对: 真相源用一套最表达力强的格式(推荐 Claude Code 的 frontmatter 约定), 迁移时用一个小转换脚本生成各工具要的形态。 不要反过来——不要为了迁就某个工具的弱格式, 把真相源也阉割了。
5.2 触发机制差异: 自动检索 vs 显式调用
这是最容易出问题的一类差异。有的工具像 Claude Code 那样靠 description 语义自动匹配触发 skill; 有的工具需要用户显式调用(比如打一个斜杠命令)。
这两种机制对 description 的要求完全不同:
– 自动匹配的工具, description 要写得像”检索关键词”, 把所有可能的触发说法都覆盖。
– 显式调用的工具, description 更像”帮助文档”, 用户已经知道要调它了。
应对: 把 description 写成自动匹配友好的版本(信息量大的那种总是兼容显式调用), 在迁移到显式调用工具时不需要改。反过来则会丢信息。
5.3 脚本运行环境差异
scripts/ 里的脚本依赖的解释器、环境变量、工作目录, 在不同工具下不一定一致。一个在 Claude Code 下 cwd 在项目根的脚本, 换个工具可能 cwd 在别处。
应对三原则:
– 脚本内部一律用绝对路径或相对脚本自身定位, 不假设 cwd。
– 依赖通过环境变量注入, 不硬编码。尤其涉及密钥时, 走 bootstrap 读取, 绝不写死在脚本里。
– 跨工具差异用一层适配 wrapper 吸收, 别让核心脚本里长出 if 工具==X 的分支。三个以上分支就是设计出问题的信号。
跨模型/跨 SDK 调用时还有一类隐蔽差异是错误格式不统一, 同一个失败在不同链路下报得五花八门, AI_ProviderSpecificError 报错定位与修复: AI SDK 排错 是一个具体的踩坑样本, 迁移脚本前扫一眼能省时间。
5.4 能力边界差异
不是每个工具都给 skill 同等的权限。有的能跑任意 shell, 有的沙箱限制严格; 有的能联网, 有的不行。一个重度依赖 shell 的 skill 迁到受限工具里可能直接哑火。
应对: 在 SKILL.md 里显式声明这个 skill 的依赖前提(需要 shell、需要网络、需要某个 CLI 已安装)。迁移时先核对目标工具是否满足, 不满足就降级或标记为不可用, 而不是让它在运行时静默失败。
六、团队共享: 从个人资产到协作流程
单人复用解决”我自己别重复劳动”; 团队共享要解决”全队用同一套规范, 且改动可控”。
6.1 集中仓库 + PR 流程
把 skill 仓库放团队可访问的 git 远端, 任何人改 skill 都走 branch + PR + review。这件事的价值在于: skill 是会直接影响 agent 行为的”准代码”, 一个人随手改了 commit skill 的规范, 全队的提交风格就变了。让它走 review, 和 review 代码同等对待。
git checkout -b feat/blog-skill-seo-rules
# 改 skills/blog-publish/references/seo-title-rules.md
git add . && git commit -m "feat(blog-publish): 加入 SEO 标题硬规则"
git push origin feat/blog-skill-seo-rules
# 开 PR, 团队 review 触发效果与措辞后合并
6.2 安全审查: skill 也是攻击面
这一点必须单独强调。skill 里有 scripts/, 有命令, 有时还有凭据读取逻辑。一个被污染的 skill, 等于让 agent 在你机器上跑了一段你没仔细看的脚本。 团队共享放大了这个风险——一个人引入恶意或粗心的 skill, 影响全队。
所以 skill 仓库的安全要求不能靠”感觉没问题”:
– 脚本不硬编码密钥, 走 bootstrap / 环境变量。
– review 时重点看 scripts/ 里有没有外发数据、有没有读敏感文件、有没有往临时目录写可执行文件。
– 来源不明的第三方 skill, 先在隔离环境跑过再进主仓。
“安全要的是证明而不是感觉”这个判断对 skill 同样成立, 安全不是氛围, 是证明 讲的虽然是 prompt 安全, 但”不能靠语义过滤器兜底, 要靠可验证的约束”这个内核, 直接适用于 skill 脚本审查。
6.3 文档即接口: README + 触发词索引
团队规模上来后, 别人不知道你这有哪些 skill、什么时候该用哪个。在仓库根维护一份索引, 列出每个 skill 的 name、description 摘要、依赖前提、维护人。这本质是把”文档即接口”落到实处: 一份能驱动别人正确调用 skill 的索引, 才算把这套资产建模完整了。
6.4 复用的边界: 不是所有东西都该做成共享 skill
最后一条反向提醒: 不要把什么都做成团队级 skill。高度个人化的工作习惯、一次性的探索脚本, 留在个人层就好。团队仓库里只放真正需要全队一致的东西(提交规范、发布流程、安全 checklist)。skill 太多太杂, 反而增加 description 之间的语义干扰, 让自动触发的工具选错。关于”什么该沉淀、什么该丢”, 选型层面的 AI Agent 框架全景: LangChain/LangGraph/n8n/Dify 等选型指南 给了一个可类比的取舍框架: 先定决策维度, 再决定收口到哪一层。
七、相关阅读
把这套方法论放进更大的 agent 工程图景里, 下面几篇可以接着读:
- Claude Code vs Codex vs WorkBuddy vs Zcode: AI 编程 Agent 怎么选 —— 先把工具盘子定下来。
- Agent Harness 不是要安装的软件包 —— harness 与 skill 的边界划分。
- 构建 Agent 和写软件, 是两种工程 —— 为什么 skill 要把决策和确定性执行分开。
- 把 Agent 送上生产: RAG、工程、安全、评测 —— skill 只是生产化拼图的一块。
- 开源 AI Agent 调试器 HALO: 利用 RLM 技术实现本地化闭环优化 —— skill 改完后怎么观测闭环效果。
- AI 信源指南: 收录 Karpathy、Sam Altman 等百余位顶级专家的 X 平台关注清单 —— 跟进 agent 工具演进的信息源。
如果你是从零搭 agent 开发能力, 技术社区热议: AI Agent 开发的学习路径与资源盘点 适合作为更靠前的入门索引。
八、FAQ
Q1: skill 用 markdown 写, 不会因为太”软”而不可靠吗?
可靠性不来自格式的”硬”, 来自结构和验证。把确定性逻辑沉到 scripts/(那部分是真代码, 可测), 把决策留给 SKILL.md(那部分本来就该是自然语言)。再配上 git 历史和 CHANGELOG, 你对每次改动的效果有迹可循。这比埋在 GUI 里、改了无从追溯的”硬配置”可靠得多。
Q2: 我只用一个工具, 还有必要搞这套吗?
值得做的是其中两件: git 版本化和标准化目录。这两件即使单工具、单人也立刻回本——你获得了回滚能力和清晰结构。软链/子模块/同步脚本那部分是多工具才需要的, 单工具可以先不碰, 等你哪天加第二个工具时再补, 成本也不高。
Q3: openclaw、hermes 这类工具的 skill 格式和 Claude Code 不一样, 怎么共享?
共享的是内核(提示 + 脚本目录), 不是表层格式。真相源用表达力最强的格式(推荐 Claude Code 的 frontmatter 约定)写一份, 各工具的具体格式用一层转换/适配脚本生成。具体差异在哪、怎么吸收, 见第五节”跨工具迁移”。核心是: 永远不要为了迁就某个工具的弱格式去阉割真相源。
Q4: 软链、子模块、同步脚本, 到底用哪个?
按场景: 单人单机多工具用软链(最轻); 跨项目引用、要钉版本用子模块(可锁 commit); 工具不认软链时用同步脚本(最通用)。三者可以混用, 唯一的铁律是——只有一份会被编辑的源, 其余都是只读投影。
Q5: 团队里怎么防止有人引入有问题的 skill?
把 skill 仓库当代码仓库管: 改动走 PR + review, 重点审 scripts/ 里的命令(有没有外发数据、读敏感文件、写可执行文件到临时目录), 密钥一律走 bootstrap 不硬编码, 第三方来源先隔离环境跑过再进主仓。详见第六节 6.2。
九、结语
agent 工具会一直增加, 这是确定趋势。如果你的 skill 跟着工具走, 每多一个工具就多一份要手动同步的副本, 维护成本是线性甚至超线性增长的。
换个建模方式: 把 skill 当成独立于工具存在的工程资产——纯文本、可 diff、git 版本化、一份源多处投影。这样每多一个工具, 增加的只是一条软链或一段适配, 边际成本趋近于零。
落地就三步, 今天就能起: 第一, 把散在各工具里的 skill 收进一个 git 仓库, 按标准目录结构摆好; 第二, 选软链或同步脚本, 让各工具指向这一份源; 第三, 给重要 skill 打上 tag、补上 CHANGELOG。从”四份会漂移的副本”到”一份可维护、可审计、可共享的真相源”, 差的不是工具, 是把它当资产来养的这套习惯。
