别再给每个 AI 工具重复写提示词了:一个文件夹,让 Claude Code 和 Codex 同时变聪明

我电脑里有个专门存提示词的文本：审代码一段，写周报一段，公众号改稿去 AI 味又是一段。

以前的工作流很笨：在 Claude Code 里用顺手了，切到 Codex 跑任务，又得翻出来再粘一次。粘着粘着版本就脱节了——Claude Code 这边随手改了两个边界条件，Codex 那头还是旧的。同一件事两个工具给出的逻辑对不上，最后还得花时间比对到底哪份才是最新版。

后来我把常用的几段提示词全改成了 skill。一份源文件，两个工具共用。命令不复杂，照着敲一遍就能跑通。

先说一句最近的新闻

2026 年 10 月 22 日，Anthropic 宣布把 Agent Skills 标准捐给 Linux 基金会旗下的 Agentic AI Foundation（AAIF）——之前的 MCP 也是进的这里。

按 Anthropic 官方口径，从 2025 年 12 月公开规范至今，已有 70 多个智能体平台接入，社区发布了 100 万个 skill，安装量接近 2.8 亿次。这几个数是官方口径，没有公开统计方法。另外据 Data Phoenix 的报道，AAIF 公开的项目追踪表上贡献协议当时还标着未签署，所以准确的说法是：已宣布捐赠，正在移交。

这事对日常干活的人来说就一个信号：这套格式不会被绑死在某一家厂商手里。今天写好的 skill，以后换到别的工具链大概率还能接着用。

skill 到底是什么

抛开花哨的概念，它本质上就是一个文件夹，里面塞了个名为 SKILL.md 的纯文本。

文件的最上方是一小截 YAML 配置，上下用三道短横线包起来；下面就是普通的 Markdown，写你原本让 AI 遵循的工作流。按 agentskills.io 的规范，顶部 YAML 里必填的就两项：

• name：技能名称，也就是这个文件夹的名字
• description：这技能用来干什么、AI 在什么场景下该调它

剩下的 license、compatibility、metadata、allowed-tools 全是可选字段，平时留空毫无影响。文件夹里还可以按需放 scripts、references、assets 目录来存测试脚本或参考资料，但日常用，单个 SKILL.md 就够了。

它比无脑堆提示词聪明的地方在“按需加载”。

工具启动时不会把全文直接吃进上下文，而是只读所有 skill 的 name 和 description，加起来也就百来个 token。只有当你发出的指令跟某段 description 匹配上了，它才会把对应的整个 SKILL.md 调进上下文。在本地挂十几个技能，完全不用心疼上下文窗口。

调用逻辑有两种：

一种是指名道姓。在 Claude Code 敲 /技能名，在 Codex 里敲 $技能名 或者先敲 /skills 选。

另一种是完全不管它。你在对话框里正常提要求，AI 发现语义跟某个技能的描述对上了，自己就会悄悄挂载运行。

两个工具各从哪里读

想两边通吃，先把两家的默认检索目录摸清楚。

Claude Code 认的个人全局路径在：

/SKILL.md" data-show-line-number="false">~/.claude/skills/<技能名>/SKILL.md

丢在这里，本机跑的所有项目都能读。如果只想让某个特定仓库生效，就放项目根目录的 .claude/skills/ 下。

Codex 认的全局路径在：

/SKILL.md" data-show-line-number="false">$HOME/.agents/skills/<技能名>/SKILL.md

对应的项目级目录则是仓库根目录下的 .agents/skills。

图源：developers.openai.com/codex/skills（官方文档 · Where Codex loads local skills）

两边路径截然不同，手动拷两份当然能跑，但这就又回到了“改了一头忘了另一头”的老毛病。更干脆的解法是：源文件只留一份，另一边直接建软链接指过去。

两边的官方文档都给软链接开了绿灯。Claude Code 明确表示个人和项目目录支持放软链接，扫描时会自动跟进到目标目录读取内容；Codex 的文档也写明支持 symlink 目录，扫描逻辑会顺着链接找到源文件。

图源：code.claude.com/docs/en/skills（官方文档 · Choose where skills load / Symlinked folders）

动手：从零做一个两边共用的 skill

这里拿“写周报”当例子走一遍。习惯上我把源文件放在 Codex 的目录里，再让 Claude Code 链接过来。

第一步，建目录，写 SKILL.md。

macOS / Linux 终端：

mkdir -p ~/.agents/skills/weekly-report# 用你顺手的编辑器新建 ~/.agents/skills/weekly-report/SKILL.md# 内容可以直接复制文末的「写周报」模板

一定要核对文件夹名跟 YAML 里的 name 是不是完全一致，这里全叫 weekly-report。

第二步，给 Claude Code 建软链接。

mkdir -p ~/.claude/skillsln -s ~/.agents/skills/weekly-report ~/.claude/skills/weekly-reportls -l ~/.claude/skills

跑完 ls -l，如果看到 weekly-report 后面带个箭头直指 .agents 下面的路径，链接就算接上了。以后模板有什么迭代，只改 ~/.agents/skills/weekly-report/SKILL.md 即可。

如果习惯用 Git 维护配置，完全可以建一个类似 ~/my-skills 的私有仓库放源文件，再把两边工具的目录都软链过去。

Windows 用户要在 cmd（命令提示符）里用 mklink，%USERPROFILE% 就是用户根目录：

mkdir "%USERPROFILE%\.agents\skills\weekly-report"mkdir "%USERPROFILE%\.claude\skills"mklink /D "%USERPROFILE%\.claude\skills\weekly-report" "%USERPROFILE%\.agents\skills\weekly-report"

Windows 下有个权限坑需要留意。微软安全策略默认只给管理员权限开放符号链接创建，普通 cmd 窗口执行 mklink /D 很容易提示权限不足。处理方式有两种：要么直接右键“以管理员身份运行”打开 cmd；要么去系统里把开发者模式打开。按微软文档说明，Win10 创意者更新之后只要开了开发者模式，普通终端也能直接建软链接。Win11 25H2 及以上版本，这个开关在“设置 > 系统 > 高级”里。在有统一管控的公司电脑上，这个选项可能会被 IT 锁死。

退一步也可以把参数换成 /J 做目录联接（junction）。不过微软文档注明联接只支持本机绝对路径，不能跨网络驱动盘。另外两家官方文档白纸黑字写的都是 symlink，没提 junction 支持情况，用 /J 的话后文的验证步骤必须盯紧点。

第三步，跑校验。

Agent Skills 官方在 GitHub 仓库（agentskills/agentskills）放出了一个名为 skills-ref 的自检工具。拉下来直接在虚拟环境里装：

git clone https://github.com/agentskills/agentskills.gitcd agentskills/skills-refpython -m venv .venvsource .venv/bin/activate      # Windows PowerShell 用 .venv\Scripts\Activate.ps1pip install -e .

装好后执行验证：

skills-ref validate ~/.agents/skills/weekly-report

格式合规会输出 Valid skill；字段有偏差、命名有大写、或者文件夹和 name 对不上，终端里会直接指出具体行。这玩意儿是官方的示范实现，平时用来挑错刚刚好。

第四步，两边实地唤醒一次。

别跳过这步。路径配好了，必须让大模型亲口告诉你它看到了。

Claude Code 敲新会话，问它一句 What skills are available?，或者直接敲 /weekly-report，看它能不能调出技能。

Codex 里另起一行，打 /skills 看看列表里有没有 weekly-report，或者敲 $weekly-report 实测。Codex 文档提到它会自动感知目录变化，要是没刷出来，关掉重开一次就行。

两端都能正常呼出，这套共享配置才算跑通。如果有一边死活认不出来，优先回去查软链接路径指没指对，再用 skills-ref 测一遍格式。

description 决定它会不会被想起来

在放模板之前得单独聊聊 description。一个技能平时能不能被精准触发，全看这一两句话写得透不透。模型就是顺着这段文本来评估意图的。

官方规范给过很具象的反例：写个 Helps with PDFs.，跟没写一样；像样的写法得把活儿拆开——提取纯文本与表格、处理表单填写、合并多页 PDF，末尾必须补上典型触发词，比如“当用户要求处理 PDF、表格抽取、文档分析时调用”。

我的习惯就两句话：头一句讲功能边界，第二句直接塞自己平时的口语习惯，比如“写周报”“把这周的活儿理一下”。口语化的触发短语写得越贴近日常表达，两边的模型就越容易对号入座。要是发现某个技能总在八竿子打不着的时候跳出来插嘴，那就是范围写得太泛了，得往回缩缩。

三个拿来就能用的模板

下面三个模板只包含规范内的标准字段，命名也卡死了小写中划线，拷走后可以拿 skills-ref validate 顺手过一遍。注意：文件夹名字必须改成和 YAML 头里的 name 一字不差。

description 用了中文加末尾英文的混排，高频词尽量往前堆，防着模型因为窗口挤压做截断。记得顺手把 author 换掉。

模板一：代码审查，文件夹名 team-code-review

---name: team-code-reviewdescription: 按团队清单审查代码改动，输出分级问题列表。用户说“帮我审一下代码”“review 这个 diff/PR”“提交前检查一下”时使用。Review code changes against a team checklist.license: MITmetadata:  author: your-name  version: "1.0"---# 团队代码审查## 先拿到改动1. 用户贴了 diff 或文件，就审贴出来的内容。2. 用户没贴、但当前在 git 仓库里，先运行 `git diff HEAD` 看未提交的改动；改动为空就直接告诉用户“没有未提交的改动”。## 按这个顺序看1. 正确性：逻辑错误、边界条件（空值、空列表、越界）、并发和重复提交。2. 安全：硬编码的密钥或口令、SQL/命令拼接、未校验的外部输入。3. 错误处理：异常有没有被吞掉，报错信息能不能帮人定位问题。4. 可读性：命名、过长的函数、重复代码。5. 测试：改了行为的地方有没有对应测试。## 输出格式- 先用一句话总结这次改动做了什么。- 再按「必须改 / 建议改 / 可以不改」三档列问题，每条写清：文件名和行号、问题、改法。- 没发现问题的档位写“无”，不要硬凑。- 不要直接修改代码，除非用户明确要求。

模板二：写周报，文件夹名 weekly-report

---name: weekly-reportdescription: 把零散的工作记录整理成一份结构清晰的周报。用户说“写周报”“整理本周工作”“帮我汇总这周做了什么”时使用。Turn raw work notes into a weekly report.license: MITmetadata:  author: your-name  version: "1.0"---# 写周报## 输入用户会给你这周的零散记录：聊天截图里的文字、待办清单、git 提交记录、会议纪要都有可能。信息不够时，先问清楚这周的起止日期和汇报对象，再动笔。## 结构1. 本周完成：按项目分组，每条写“做了什么 + 结果”，能量化就量化，数字只用用户给的，不要自己编。2. 进行中：当前进度、预计完成时间、卡在哪里。3. 风险与需要的支持：写清楚需要谁、在什么时间之前、帮什么忙。4. 下周计划：3～5 条，按优先级排序。## 写法要求- 用短句，一条一行，不写空话套话。- “优化了一些功能”这类模糊说法，要改成具体做了什么。- 用户没提到的工作不要补，拿不准的地方用【待确认】标出来。- 整份周报控制在一屏能看完的长度。

模板三：公众号去 AI 味润色，文件夹名 wechat-polish

---name: wechat-polishdescription: 给公众号文章去掉 AI 腔，改成像真人写的白话。用户说“润色公众号文章”“去 AI 味”“改得像人写的”时使用。Polish WeChat article drafts to remove AI-sounding phrasing.license: MITmetadata:  author: your-name  version: "1.0"---# 公众号去 AI 味润色## 原则只改说法，不改事实。原文里的数字、日期、人名、引用一律保留；觉得有问题的地方，用【存疑：原因】标出来，交给作者判断。## 重点处理这些1. 套路开场：“在当今快速发展的时代”“随着 AI 技术的不断进步”之类，直接删掉，从具体的事或具体的问题写起。2. 空洞总结：“总而言之”“综上所述”“让我们一起期待”，删掉，或者换成一句具体的建议。3. 排比堆砌和三连形容词：留下最准的一个。4. 翻译腔：“进行一个优化”改成“优化”，“对……进行分析”改成“分析……”。5. 过多的加粗、破折号和感叹号：每段最多保留一处强调。6. 模板小标题：“一、背景”“二、核心要点”这种，改成能说明这一节内容的具体短句。## 输出1. 先给出改好的全文。2. 再列出改动最大的 5 处：原句 → 新句，每处附一句理由。3. 不新增原文没有的观点或案例。

这几个坑我替你先看过文档了

名字限制很多。按规范要求，name 最长只能写 64 个字符，且只能包含小写字母 a-z、数字 0-9 和短横线 -。开头结尾不能挂连字符，中间不允许出现 -- 连用，并且必须和文件夹同名。写成 PDF-Processing（带大写）或者 pdf--processing（双连字符）都会直接挂掉。Claude Code 宽容一点，允许空着 name 直接继承文件夹名；但 Codex 严格执行标准，缺少 name 和 description 根本不认。想两头兼顾，老老实实写全。

留神系统内置指令。Claude Code 自身就挂了个 /code-review，官方文档写得直白：要是你的自定义 skill 也起这个名，它会把原生命令强行覆写掉。上面的模板刻意用了 team-code-review，就是为了把内置命名让出来。

私有字段别往通用文件里塞。Claude Code 提供了不少专属控制项，比如 argument-hint、disable-model-invocation、context。在本地跑确实方便，但只要你想把这个 skill 扔给 claude.ai、通过 Skills API 调用、或者跑官方打包脚本，系统看到这些非标字段就会直接抛出类似 Unexpected key(s) in SKILL.md frontmatter: argument-hint 的报错。skills-ref 也会当场亮红灯（Unexpected fields）。Codex 的做法就相对克制，它把展示名称、路由逻辑挪到了 skill 目录下的 agents/openai.yaml 独立存放。既然要多端复用，SKILL.md 的 YAML 头部就只留标准字段。

描述文本不仅限长，还会被无情切断。规范卡死的长上限是 1024 字符。Claude Code 在展示技能列表时，会把 description 和 when_to_use 拼到一起切到 1536 字符以内；Codex 默认留给技能列表的预算只有上下文窗口的 2%（没拿到具体窗口大小时按 8000 字符死算）。只要挂载的技能数量上去，系统第一件事就是削减你的 description。关键触发短语一定要死死焊在最前面。

云端会话读不到本机路径。Claude Code 文档提过，Cowork 环境以及纯云端运行的 session 根本没有权限抓你电脑本地的 ~/.claude/skills。遇到这种场景，要么在 claude.ai 账号设置里手动打开开关，要么把技能提交进对应 Git 仓库的 .claude/skills 下。

来路不明的脚本千万别盲跑。skill 是具备代码执行能力的，里面随时能塞自动化 shell 脚本，还能借助 allowed-tools 预先提权。Claude Code 官方反复告诫过，克隆仓库里自带的 skill，执行前一定要仔细看一眼它的权限清单。网上拷来的配置文件，把 SKILL.md 和 scripts/ 底下的源码过一遍，确认它调了什么系统命令、碰了哪些目录。看不明白就先别用。

我现在的习惯

我现在基本形成了肌肉记忆：一段提示词只要在各个窗口间复制了两次以上，它就该变成一个 skill 了。

物理文件只留一份，两边各自敲一行确认跑通。改动随手保存，双端立刻同步，终于不用开着好几个文本编辑器人肉同步版本了。

找一段你平时用得最频繁的提示词，按上面的流程建个目录试一次，两分钟就能弄好。