编码智能体在别人的仓库里表现差，多半不是模型的问题，而是仓库没有告诉它该怎么工作：构建命令在哪、测试怎么跑、PR 要遵守什么惯例。ai-ready 是一个 Agent Skill，跑一次就分析代码、CI、测试、文档与目录结构，生成 AGENTS.md、copilot-instructions、CI 与 issue 模板这些配置文件，而且产出是按项目定制的内容而不是通用模板。这篇教程走一遍完整流程：两种安装方式、首次生成、读懂 AI 就绪度报告、用排除项跳过不需要的部分、再跑一次让它审计漂移，最后说明它为什么只提建议而不覆盖你的文件。

同一个编码智能体，在自己维护的仓库里顺手，换到半年没整理的老项目里就开始乱猜：构建命令试错、测试不跑、提交信息风格随缘、PR 模板当作不存在。多数时候不是模型变笨了，而是仓库没有一个地方写清楚「在这里该怎么干活」。AGENTS.md、copilot-instructions 这类文件就是为此存在的，问题在于没人愿意一条条写。

ai-ready 是一个 Agent Skill，做的就是这件事：分析你的代码、CI、测试、文档与目录结构，生成按项目定制的配置文件，而不是丢一份通用模板给你。它按 Agent Skills 标准分发，Claude Code、GitHub Copilot、Codex、Cursor 都能用。

第一步：选一种安装方式

# 通用方式：覆盖 70 多个支持 Agent Skills 的智能体
npx skills add johnpapa/ai-ready

# 或者走各工具自己的插件市场
# GitHub Copilot CLI
copilot plugin install ai-ready@awesome-copilot
# Claude Code（两条命令）
/plugin marketplace add johnpapa/ai-ready
/plugin install ai-ready@johnpapa-ai-ready
# OpenAI Codex（两条命令）
codex plugin marketplace add johnpapa/ai-ready
codex plugin add ai-ready@johnpapa-ai-ready
# Cursor：把 skills/ai-ready/ 拷进 ~/.cursor/skills/ai-ready/
# 其它工具：拷进 ~/.agents/skills/ai-ready/

两处容易踩：Claude Code 与 Codex 需要两条命令——第一条注册 marketplace，第二条才真正安装插件，只做一条会以为装好了其实没有；装完必须重启智能体，多数工具只在启动时扫描技能目录。~/.agents/skills/ 是厂商中立的目录，Codex 与 Cursor 都会读，所以最后一行的做法对大多数工具都成立。

第二步：生成

装好之后直接用自然语言触发即可，也可以显式调用技能名：Claude Code、Cursor、Copilot CLI 里输入 /ai-ready，Codex 里输入 $ai-ready。从市场安装时 Claude 会带命名空间，写成 /ai-ready:ai-ready。

make this repo ai-ready

第三步：先看报告再落地

它会先产出一份 AI 就绪度报告——包含分析结论与建议的改动，而不是直接写文件。如果只想看现状，可以要求它只报告不生成：

how ai-ready is this repo?
score this repo

这个顺序值得坚持：先看它认为你的仓库缺什么，再决定让它写哪些文件。对多人协作的仓库，生成 AGENTS.md 等于新增一条团队约定，值得先过一遍评审。

第四步：用排除项收窄范围

make this repo ai-ready but skip CI and issue templates
just generate AGENTS.md and the per-tool pointer files

把不想动的部分直接写进指令里，它会照做。对于已经有成熟 CI 与 issue 模板的仓库，这一步能避免它生成一堆重复文件。

第五步：定期重跑，让它审计漂移

第一次运行：创建缺失的配置文件
之后每次运行：进入审计模式，把现有文件与代码库的当前状态对比，标出过时的构建命令、已经变化的目录结构、以及新出现但还没写进约定的 PR 评审习惯
它不会覆盖你的文件：只给出建议，改不改由你决定

更新技能本身也分工具：skills CLI 用 npx skills update，Copilot CLI 用 copilot plugin update ai-ready，Claude Code 用 /plugin marketplace update johnpapa-ai-ready，Codex 用 codex plugin marketplace upgrade。

几个已知的坑

智能体不认这个技能：先重启；再确认装上了（npx skills list、copilot plugin list、claude plugin list、codex plugin list），最后直接点名调用排除匹配问题
安装报 reference is not a tree：说明 marketplace 里指向的是 commit SHA，而插件安装用的是 git clone --branch，只接受分支或标签，需要改成 v1.3.0 这样的发布 tag
Claude 的 /plugin marketplace add 走 SSH 报认证错误：换成完整 HTTPS 地址，或者让 git 对 github.com 优先走 HTTPS

这类工具的价值不在生成一次文件，而在让规范跟着代码走——每次重跑都能告诉你，哪些说明已经和仓库对不上了。