先对号入座。你大概率有一份这样的经历：周一告诉 AI「这个项目用 pnpm，别用 npm」，周三新会话它又 npm install 了；纠错记录散落在几十个会话日志里，换台电脑、换个工具，全部蒸发；硬着头皮让 AI 写一份项目规范，得到一个 500 行的「最佳实践」堆——一半是常识，一半是从没跑过的命令。文件越胖，读它的 AI 越是选择性失明。

agentsmd-skill 就是为这些时刻做的：把这次会话踩的坑蒸馏成一行一条的可执行规则，写进项目根目录的 AGENTS.md。从此每个新会话——Claude Code、Codex、Cursor 都一样——开工前先读它，照着做。它守四条底线：一条规则只说一件事、全文不超 120 行、写进去的命令必须真跑过、所有改动先给你批准。

这篇文章不讲设计原理（那篇早就写过了），按五个真实场景讲它什么时候用、怎么用。

场景一：同样的坑，每次会话都要重新踩一遍

最常见的场景。这次会话里你纠正了 AI 三次：测试要先起本地数据库、部署脚本别碰 main 分支、报错先看 pnpm logs。下次会话，它照犯。

会话收尾时说一句：

把这次会话踩的坑固化成项目规则

它会走一条固定流水线：先收集——你指出的错误、真实撞上的坑、重复两次以上的偏好才算数，一次性细节和常识直接排除；再蒸馏——泛化、压成一行、归入最贴的章节，过「会再遇到、违反有损失、一行说得清」三道准入，缺一道就丢；然后和现有规则做合并比对——等价的丢弃、重叠的合并、冲突的保新的；最后把完整变更方案摆给你，批准了才动文件。

场景二：AGENTS.md 已经写成了垃圾堆

如果规范文件已经四五百行，规则互相打架、常识占半壁江山，AI 读它约等于没读。

还是一句话：

更新项目规范：按合并决策表并入这次的教训，超 120 行先删后加

它做的是有机合并而非追加：五道闸门（等价丢弃 / 重叠合并 / 特例被通用版本替换 / 冲突保新 / 过时删除）筛完，逼近 120 行硬上限就先削减再新增。仍有价值但不达标的内容——比如一段低频操作细节——迁往 docs/<主题>.md，根文件留一行引用。删的是冗余，不是记忆。

场景三：新项目冷启动，想要一份能跑的规范

新项目还没有 AGENTS.md，你想要一份从目录结构、README 和构建配置长出来的首版规范，而不是模板填空。

还没有 AGENTS.md——用 agentsmd 生成首版，命令逐条实跑验证

这一步的差异点在命令验证：写入的每条构建、测试命令逐条实跑；部署、迁移这类不便实跑的，与 package.json scripts、Makefile、CI 配置逐一核对，对不上不写入。为什么这么轴？因为这个文件对 AI 来说是「可信上下文」，一条假命令比十条缺规则更致命——agent 会信以为真地执行。这是发布后被真实使用打脸换来的规则。

场景四：目录里没有代码，全是文档和数据

报告库、写作协作目录、数据空间——没有 package.json，「构建命令」「lint 规范」这些章节毫无意义，它们真正要管的是数据口径、命名归档、交付复核。

给这个协作目录沉淀工作规则，并归集散落的报告、数据和参考资料

流程开始前会先判定这是 coding 还是 work 场景：work 场景扫描文档结构和命名约定，规则偏向数据定义、归档与交付；归集时文档进 docs/、机器可读数据进 data/、参考资料进 references/。移动前先全项目查引用，被引用的文件不动，移完逐个修断链——而且所有移动都要你批准。

场景五：你的 agent 有个人记忆，但和项目脱节

Hermes、OpenClaw 这类带记忆机制的个人 agent，记忆条目常常和具体项目对不上：这条教训属于哪个项目？下次在这个项目里还适用吗？

顺手的做法是固化教训时捎带一句：

把教训写进 AGENTS.md，并归集散落在根目录的文档和数据

它不建私有记忆格式，完全搭宿主便车：agent 有记忆机制，项目记忆就按宿主自己的格式沉淀，先查重、经批准再写入；没有记忆机制就静默跳过。TODO 和 CHANGELOG 也一并更新。装在哪个 agent 里，就长成那个 agent 的样子。

安装与更新

三种方式任选，skills.sh 数据显示最常用的是第一种：

# 方式一：skills CLI（推荐，可一句话更新）
npx skills add kelegele/agentsmd-skill
npx skills update agentsmd   # 以后更新

# 方式二：git clone（全局装到 Claude Code；项目级用 .claude/skills/agentsmd）
git clone https://github.com/kelegele/agentsmd-skill.git ~/.claude/skills/agentsmd
git -C ~/.claude/skills/agentsmd pull   # 以后更新

# 方式三：不想装任何东西？把仓库地址丢给你的 agent
# "Install this skill for me: https://github.com/kelegele/agentsmd-skill"

也在 ClawHub（clawhub install agentsmd）和 LobeHub Skills Marketplace 上架了。装完部分 agent 需要重启或开新会话才加载。AGENTS.md 本身遵循开放规范，Claude Code、Codex、Cursor、Gemini CLI、OpenCode、WorkBuddy 读的是同一个文件。

三个高频疑问

会不会让 AI 堆一堆通用常识凑数？ 不会。「三道准入」是硬流程，为凑数堆常识被明确写进了禁令——一次性细节和常识在收集阶段就被排除。

文件会不会无限长？ 不会。120 行硬上限，追加被禁止，超了先削减；有价值的细节迁去 docs/，根文件留一行引用。

会不会不经我同意就改文件？ 不会。AGENTS.md、记忆、进度文件、移动文档，全部先出完整方案、批准后才执行。

现在就开始

最小成本的开始方式：挑一个你反复纠错的项目，装上，然后让 AI 把这次会话的教训固化进去。看一遍它给出的变更方案——哪些进、哪些合并、哪些删、每条规则为什么这样写——你会立刻知道这东西是不是你的菜。

仓库在 GitHub，问题和想法欢迎提 Issues。想深挖设计的，读设计哲学篇；想知道这七个版本是怎么被真实使用打出来的，读迭代复盘篇。