一个 SKILL.md 同时喂两个 Agent：写 AI 技能文件的实操经验

作者团队在工作室里维护 23 个 skill，同一份 SKILL.md 同时驱动 Claude Code 和 Codex CLI。文章给出完整格式、真实案例和踩坑清单，核心结论是：description 决定技能何时被加载，写它要像写触发词，而不是写摘要。

SKILL.md 的最小结构

• 一个 skill 就是一个文件夹加一个 SKILL.md：front matter 写 name 和一行 description，正文是纯文本指令
• description 是关键——agent 平时只读这一行，任务匹配上了才加载全文，以此节省 context
• Claude Code 中项目级 skill 放在 .claude/skills/<name>/SKILL.md，脚本、示例、风格指南等附加文件放同一文件夹
• skill 应随仓库进版本控制，改动走 pull request 审查，因为改一步就改变所有 agent 的后续行为

为什么 description 决定加载与否

• agent 不可能每次任务前读完 23 个长文件，所以只维护一份名称和描述的短清单
• description 承担路由功能：要按匹配来写，而不是当文件摘要写
• 对比案例：'Video helper' 几乎不会被匹配；'Render an approved episode into its Short. Use when the owner says make the video or render episode sd-N.' 则在有人说 make the video 时精准触发
• 这种用短描述匹配请求的机制，和 MCP 的工具发现是同一个思路

一份文件驱动两个 agent

• Claude Code 原生读取 .claude/skills；Codex CLI 在 prompt 里加一行：任务提到 SKILL.md 时读取并遵循
• 同一个 735 词的 make-video/SKILL.md，无论 Claude 还是 Codex 执行渲染都走同一套步骤
• 改步骤时两个 agent 下次运行自动生效，因为读的是同一个文件
• 纯 Markdown 格式不绑定任何厂商特性，换 agent 也能继续用

现在写 skill 的六步流程

• 先手动把活干一遍，记下实际走的步骤
• 在 description 里写明触发词：人们想让这件事发生时会输入的原话
• 步骤用编号，每条一个动作，带具体命令或文件路径，不写段落式建议
• 结尾加检查项：什么算完成、什么绝对不能变
• 引用文件而不是粘贴内容，脚本和风格指南放在 SKILL.md 旁边
• 用一个不点名 skill 的普通请求来测试；没加载就改 description，而不是改步骤

踩过的三个坑

• 描述太模糊：早期 skill 只说'我是什么'，不说'什么时候用'，导致加载太晚或根本不加载
• 一个 skill 覆盖三个任务会为三个任务都加载，互相干扰，应拆分
• 只有规则没有检查：'写得简洁点'没用；'句子不超过 25 词，逐句数'才有效

诚实评价

• 优点：纯 Markdown、跨 agent 通用、能在 PR 里审查、把一个人的经验变成全团队可复用的流程
• 局限：skill 好坏取决于 description；过长的 skill 加载时消耗 context；agent 仍可能跳步，所以结尾的检查项很重要
• 作者判断：多数人会装一百个 skill 只用四个，四个在正确时机触发的 skill 比一百个闲置的更有价值