Skill 和 AGENTS.md：生态的标准，自己的规矩

你大概也干过这件事：给 AI 编程助手立规矩——开一个文档，格式自己定，文件名自己起，RULES.md、GUIDE.txt，或者一段存了半年的提示词。规矩写得挺认真，可换个工具就作废：新助手不认识你的文件名，整套规矩得重新口述一遍。

先说结论：给 agent 立规矩这件事，标准已经出现并且赢了。项目说明书有 AGENTS.md，可复用能力有 Skill，自造格式不是个性，是主动退出生态。但这只是故事的一半——标准解决的是「壳」，壳里装什么：你项目的真规矩、你开工的老习惯，恰恰只有你能写。这篇讲清楚四件事：为什么直接用标准、什么时候值得写 Skill、AGENTS.md 为什么必须亲手写，以及我们的 init Skill。

速览：

• AGENTS.md 已被 24 款主流工具原生支持，GitHub 上六万多个开源项目在用；Skill 规范由 Anthropic 开源，正被越来越多 agent 产品采纳
• 规模效应三个来源：模型原生认识这个格式、社区技能装上就用、格式演进有人维护
• 写 Skill 的判定线：同一套多步流程向 agent 交代过三次以上，就该抽成文件
• AGENTS.md 管项目（跟着仓库走），Skill 管流程（跟着人走），两层不冲突
• 工具自带的 /init 产出的是通用仓库摘要；你自己的 init Skill 固化的是你的工作习惯
• 我们的 init Skill 四步：调研项目生成 AGENTS.md、建临时目录、配 .gitignore、git 收尾，全程幂等

为什么别自造规范：AGENTS.md 和 Skill 已经赢了

先看两个标准现在的位置。

AGENTS.md 是放在仓库根目录、写给 AI 编程助手看的项目说明书——README 给人读，它给 agent 读。这个格式由 OpenAI、Google、Cursor 等厂商共同推动，现在由 Linux 基金会旗下的 Agentic AI Foundation 托管；官方网站列出的原生支持工具已有 24 款，从 OpenAI Codex、Gemini CLI 到 Cursor、GitHub Copilot1。GitHub 上六万多个开源项目在用，规范甚至设计了嵌套规则：monorepo 里离你正在改的文件最近的那份说了算1。

Skill 是把一类活的完整做法打包成一个文件夹：一个 SKILL.md 写清「我是谁、什么时候用我、步骤是什么」，旁边可以挂模板、脚本、参考文档。格式由 Anthropic 提出，2025 年底作为开放标准开源，规范和 SDK 都公开可取，任何 agent 产品都可以实现2。

你可能会想：格式而已，我自己定义一个不行吗？行，但你要独自面对三件事。

第一，模型得现场学你的格式。agent 对 AGENTS.md 是自动发现、启动即加载；对 Skill 则靠 frontmatter 里的描述做路由——先只加载每个 Skill 的名字和描述，被触发了才读正文，长任务也不会撑爆上下文3。这些适配是厂商在模型和产品层调过的。你自造的格式没人调过，agent 只能靠你贴进对话的现场教学，文档一长就开始丢信息。

第二，复用经济归零。没有人自造 WordPress 插件格式，所以几万个插件能互通——你写一个，全世界都能装。Skill 同理：社区里现成的技能装上就用，你沉淀的技能换个项目、换个工具也能带走。自造格式，这一切与你无关。

第三，演进没人替你扛。标准由基金会托管、社区维护，格式怎么升级、怎么兼容是大家的事；你的私有格式，维护者名单上永远只有你一个。

一句话：自造规范省下的学习成本，远小于退出生态付出的代价。这不是口味问题，是经济学问题。

什么时候值得写成一个 Skill

标准好用，但不是所有事都值得做成 Skill。判定线就一条：同一套多步流程，你向 agent 交代过三次以上，就该抽出来了。

适合的信号很明确：流程多于一步、输入输出稳定、步骤里埋着只有你知道的坑。我们日常挂着几十个 Skill，从发布 npm 包、生成配图到初始化项目，全是这种「每次都一样、每次都容易漏」的活。比如发包流程里「发布前先 npm pack 检查要发布的内容」这条教训，口述过两遍，第三遍就该变成文件。

反过来说，一次性任务、一句话能说清的任务，直接说就行，包成 Skill 反而多一层间接。Skill 的本质是把口述经验固化成可复用的文件：description 是写给模型看的路由信息（什么时候想起我），正文是写给执行者的操作手册（拿到之后怎么干）。一个 Skill 好不好用，一半取决于 description 有没有写清触发时机和边界。

AGENTS.md 管项目，Skill 管流程

两个标准不冲突，因为它们管的是两层事：

• Skill 跟着人走：跨项目复用的「这类活怎么干」——怎么发包、怎么出图、怎么初始化
• AGENTS.md 跟着仓库走：单个项目的「这里是什么、什么不能碰」——技术栈、验证命令、红线

为什么 AGENTS.md 的内容必须亲手写？因为工具调研得出仓库的表面事实，调研不出你的真规矩。「双语文案必须两边同步更新」「改完文章必须跑哪个命令」「push 到 main 会不会触发部署」——这些约定活在维护者脑子里，通用模板生成不出来。规范还特意把门槛放到最低：无必填字段、纯 Markdown、写多少算多少1——正因为是空壳，才轮到你往里装真东西。

收益立竿见影：一是每次开工的口述成本归零，新会话进门就带着规矩；二是红线有了兜底——「不要自行 push」「不碰生产服务器」一旦写进 AGENTS.md，每个会话都会读到，你不用再人肉盯防。

初始化项目：别用工具自带的 /init

说到这儿就到了最典型的场景：接手一个新目录，怎么让 agent 快速就位？

很多 agent 工具自带 /init 命令：扫描一遍仓库，生成一份 AGENTS.md。它不是不能用，而是它的产出只是一个通用仓库摘要：技术栈、目录结构、构建命令，谁家的 /init 生成都长得差不多。它调研仓库，但不认识你：不知道你的 AGENTS.md 该有哪几个固定章节，不知道你要留临时目录，更不知道你提交代码的纪律。

我们的做法是把初始化做成自己的 init Skill。区别不在自动化程度，在固化的是谁的知识：自带 /init 固化的是「如何总结一个仓库」，我们的 init Skill 固化的是「我习惯怎么开工」——AGENTS.md 按我的模板长出来，git 按我的纪律收尾。新项目开工，一句话的工夫，得到的不只是一份说明书，而是一个按你习惯铺好的工作区。

我们的 init Skill 长什么样

最后把我们维护的 init Skill 拆给你看。

整个 Skill 三份文件：主文件 63 行，只写外层流程；一份近百行的《AGENTS.md 撰写规范》放在 references/ 子目录，管模板和调研要求；再放一份真实成品示例。这个分层本身就是 Skill 写作的经验：外层薄、内层厚，用到才加载，和 Skill 规范的渐进披露是同一个思想。

frontmatter 只有两个字段，最值钱的是 description——它同时写了触发场景（「初始化项目」「新项目开工」「参考某某项目写一份 AGENTS.md」）和排除条款（只想要 AGENTS.md 时仅执行第一步）。这半段是写给模型的路由器，值得反复打磨。

正文是四步工作流：

## 1. 生成 AGENTS.md
- 先通读 references/ 里的撰写规范，再照它执行
- 调研项目事实：README、package.json、git log、CI 配置——只写查证过的
- 项目已有 AGENTS.md：跳过，不重写

## 2. 初始化 .temp 目录
- 草稿、实验脚本的容身之处，不入库

## 3. 配置 .gitignore
- 只在文件末尾追加，其他内容一律不动

## 4. Git 收尾（三分支）
- 无仓库 → init 后整体首提交（提交前预览，发现密钥先问）
- 已有仓库 → 只提交 .gitignore，路径限定，绝不夹带暂存区里别人的改动
- AGENTS.md 已被跟踪 → 先问，未确认不动

三条设计原则值得抄走：

• 幂等：每步先查再动，重复执行不产生重复结果——init Skill 不是一次性脚本，是随叫随到的流程
• 红线写进正文：「已有仓库禁止 git add -A」不靠模型自觉，靠白纸黑字
• 模板与流程分离：模板升级改 references，流程升级改主文件，互不牵连

这个 Skill 的默认选择是 AGENTS.md 与临时目录都不入库、留在本地。如果你的团队希望项目约定跟着仓库走，改掉这条就好——模板是自己的，怎么改都行。

标准是壳，习惯是芯

收回来。要不要用 Skill 和 AGENTS.md，不是口味之争：自造格式等于独自维护一个没人兼容的规范，用标准等于免费拿走 24 款工具的适配、一整个社区的技能积累和一份有人维护的演进路线，这买卖没有悬念。

但生态给你的始终只是容器。容器里装什么——你对这个项目的理解、你踩过的坑、你开工的顺序——规范帮不上忙，也不该帮：那是你的工作方式本身。把这两层分开，结论就朴素了：格式上从众，内容上从己。生态负责让 agent 认得你的文件；认得你的工作，得靠你自己写下来。