ai-ready

AI 就绪仓库技能

角色设定

以经验丰富的仓库维护者的视角开展工作。优先考虑如何减轻审查负担并降低贡献者的阻力。你生成的每个文件都必须有存在的价值——通用样板只会制造噪声。

---

按顺序执行以下步骤，分析当前仓库并生成所有缺失的 AI 就绪配置资源。

首次运行与再次运行：首次运行时，大多数资源都不存在——此技能会创建它们。再次运行时，会根据当前代码库审查现有资源，检查内容是否偏离、是否过时，以及近期 PR 审查中出现的新约定。

**跳过资源：**如果用户的提示要求跳过特定资源，请遵守这些排除项。仍须完整执行分析，但跳过被排除资源的生成。

**仅报告模式：**如果用户要求生成报告而不创建文件（例如“这个仓库的 AI 就绪程度如何？”“给这个仓库评分”），请完整执行分析（步骤 0–1）并显示报告（步骤 11），但跳过所有生成步骤（步骤 2–10）。

11 项跟踪资源

资源分为三个类别。评分时，统计状态为做得很好的资源数量。

🤖 AI 上下文——AI Agent 用来了解仓库的内容

#	资源	生成步骤
1	AGENTS.md	步骤 2
2	各工具指引文件（.github/copilot-instructions.md、CLAUDE.md、……）	步骤 3
3	维护矩阵（位于 AGENTS.md 中）	步骤 2
4	审查 Agent（.github/agents/）	步骤 4c
5	入门技能（.github/skills/）	步骤 4d
6	安全技能（.github/skills/，存在相关使用面时）	步骤 4e

🔧 开发工作流——让 PR 保持整洁并帮助贡献者有序推进的内容

#	资源	生成步骤
7	CI 工作流（.github/workflows/ci.yml）	步骤 5
8	问题模板（.github/ISSUE_TEMPLATE/）	步骤 6
9	PR 模板（.github/PULL_REQUEST_TEMPLATE.md）	步骤 6

📖 入门指引——帮助新贡献者上手的内容

#	资源	生成步骤
10	更新日志（CHANGELOG.md）	步骤 9
11	文档（或明确注明“不需要”）	步骤 10

**评分：**🟩 做得很好（计入评分）· 🟨 有待改进（不计入评分）· ⬜ 缺失（不计入评分）。 奖章、限制奖章等级的两项前提条件，以及评分不得声称的内容，均见于 references/report-template.md——请在步骤 11 中阅读。

---

步骤 0——自动检测 GitHub 上下文

此技能以 GitHub 为核心——通过 GitHub 工具发现所有信息。

0a. 确定仓库

运行 git remote -v 提取 GitHub 的 owner/repo。如果不是 GitHub 仓库，则退回到仅限本地的分析。

0b–0d. 获取元数据、分析 PR 审查记录、检查社区健康状况

使用 GitHub MCP 工具或 gh CLI 自动发现仓库元数据、PR 审查模式和社区健康缺口。完整 API 表、PR 分析方法及健康缺口映射见 references/github-discovery.md。

来自人类和审查 Agent 的重复审查反馈，会成为 AGENTS.md 中的约定。近期出现的模式应获得更高权重；如果某项约定已不再适用，应将其标记为已废弃，而不是重新当作现行规则。

---

步骤 1——分析代码库

GitHub 上下文告诉你仓库是什么。本地分析则告诉你它如何运作。结合步骤 0 中的 GitHub 上下文，使用 glob、grep 和 view。

1a. 检测语言、框架和仓库类型

查找清单文件并提取详细信息。完整清单文件表、VS Code 扩展检测、多应用集合、演示应用模式，以及课程/教程仓库检测见 references/detection-tables.md。

课程仓库（满足 3 项或更多信号：带编号的文件夹、课程关键词、没有主应用）应调整步骤 2–5。完整信号列表和步骤调整说明见 detection-tables.md。

1b–1c. 检测测试配置和 CI

社区工作流（过期清理、欢迎、标签）也是有效的自动化，并不代表缺少 CI。 不要因为仓库唯一的工作流是过期机器人，就报告该仓库没有 CI。

1d. 检查现有 AI 配置

检查：AGENTS.md、.github/copilot-instructions.md、CLAUDE.md、.cursorrules、.cursor/rules/、 .github/skills/、.github/agents/、.github/extensions/、.devcontainer/。

有两种失效模式，第二种最常见。 AGENTS.md 是规范文件；其他所有指令文件都应简短地指向它。

1. 重复 — 工具文件重述了 AGENTS.md 中的约定。标记为 可以改进：重复的指导会悄然偏离，导致两个 Agent 遵循同一标准的不同版本。
2. 分散 — 每个文件包含不同内容，且都不完整。这才是大多数仓库的实际情况，而且比重复更糟糕，因为表面上看不出问题。只读取 AGENTS.md 的工具看不到这些约定；只读取 Copilot 文件的工具看不到构建和测试命令。

对于内容分散的情况，具体列出工具文件中存在、但 AGENTS.md 中没有的部分 — 这些内容需要在第 2 步纳入。此处不要重写工具文件；提出迁移建议，让用户决定。

1e–1h. 检查配置、变更日志、文档和结构

检测 CODEOWNERS、dependabot.yml、问题和 PR 模板、LICENSE、README 中的贡献指南部分、变更日志的健康状况，以及文档配置。需要注意两点：变更日志可能位于文档站点，而不是 CHANGELOG.md 中，因此报告缺失前，先沿指针文件查找；新鲜度应以最新的 git 标签为基准，而非文件日期。

1i. 汇总发现

生成结构化发现表，结合 GitHub 上下文和代码库分析，并提供文件路径证据。完整的发现表模板见 references/detection-tables.md。

列出缺失的 11 项资产。对于现有资产，将其与分析结果进行比较，并将偏差标记为“可以改进”。

1j. 检测单体仓库区域

如果找到工作区配置，列出各区域的名称、路径 glob 和主要技术栈。对于大型库单体仓库，绘制跨包依赖关系。详情见 references/detection-tables.md。

---

步骤 2 — 生成 AGENTS.md

如果仓库根目录下没有 AGENTS.md，就创建一个。如果该文件已存在，则对照分析结果进行比较，并标出偏差。

AGENTS.md 是关于此仓库工作方式的规范入口——每个工具都会读取的唯一文件，也是每项约定唯一的说明位置。但这不代表要把所有内容都放进去。生成之前，请先阅读 references/agents-md.md：了解哪些内容应写入、哪些不应写入，以及其他内容应放在哪里。

以下两条规则适用于所有内容。

1. 可发现性测试。 写任何章节之前，先问自己：Agent 能否通过阅读代码找到这条信息？ 如果可以，就不要写下来。每项任务开始前都会加载 AGENTS.md，因此每一行在每次运行时都会产生开销，并分散 Agent 对实际工作的注意力。目录树、技术栈清单和架构概要都无法通过此测试——只有在仓库确实存在出人意料的情况时才生成，并且当项目布局符合常规时应完全跳过。

2. 放在适用范围最窄的位置。 每项任务都需要 → 根目录下的 AGENTS.md。只在某个区域需要 → 在该目录中放置一个嵌套的 AGENTS.md；这是标准做法，也是单体仓库扩展的设计方式（以最近的文件为准）。仅在执行某项流程时需要 → 技能（步骤 4d）。参考资料 → 链接到文档。

从 20–30 行开始——记录 Agent 在此仓库中最常犯的错误，并且只有在实际错误证明有所遗漏时才增加内容。150 行是上限，不是目标：超过后就该移出部分内容。文件越长，效果越差，因为模型在遵循约 150–200 条指令后，遵循度就会下降；每一行也都会与已有指令争夺注意力。

生成以下内容。这些信息在代码中无处可寻，因此始终能通过测试：

• 构建、测试和运行命令——这些信息藏在工具配置中，而且每项任务都需要。不要硬编码版本；应引用清单文件。
• 无法推断的约定——读者无法从代码及其代码检查配置中推导出的语言、框架、测试和风格规则。如果代码检查工具已经强制执行了某项规则，就链接到相应配置，而不要重复说明。
• 从 PR 审查中提炼的约定（步骤 0c）
• 添加新的 [功能/模块]——完整的注册链：枚举、索引重新导出、配置声明。没人能只读一个文件就推断出完整注册链
• 常见陷阱——人们在此仓库中容易犯的错误。这些经验不会出现在代码中
• 维护矩阵——更改代码库各部分时必须更新的内容。使用真实文件路径。追踪实际依赖关系图，而不是停留在顶层文件：.csproj 的 ProjectReferences、导入链、mod 声明、__init__.py 重新导出。保留为表格；步骤 4d 会将其转化为操作流程，因此不要在这里重复编写流程。

**除非仓库存在让它们显得出人意料的情况，否则不要生成以下内容：**项目概览、CI/CD 章节、仓库结构章节或技术栈列表。这些内容会在每项任务中分散注意力，而且告诉 Agent 的都是它能自行看到的信息。

关键模式与约定这个标题通常只是上面“约定”条目的另一种说法。二选一即可。

测试约定——无法测试的说法。 如果仓库有多个测试通道——例如，一个快速的模拟单元测试通道，以及一个可访问真实框架的较慢通道，或单元测试、集成测试和端到端测试——就添加一条规则，提醒 Agent 不要轻信 PR 中“无法测试”的说法。认同之前，应搜索其他通道，查看是否已有通过模拟新代码所依赖的具体 API 或状态来进行测试的先例。某种说法在一个通道中成立，检查另一个通道后往往就不成立了；而“无法测试”最容易成为更改缺少覆盖、又无人提出异议的借口。

仅当确实存在多个测试通道时才生成此规则；单通道配置应跳过，因为这会针对仓库中不存在的情况提出建议。

几乎没有仓库具备的两个章节——生成这两个章节

两个章节中的每一行都必须能由机器判定，无需任何人解读。 失败时会返回非零退出码的命令符合要求。“编写整洁的代码”则不符合。

## Done means —— 变更完成前必须满足的条件，须根据仓库的实际命令推导。

## Never merges without a human —— 人工审核的边界，须根据本仓库中实际存在的风险路径确定，并以路径或条件表述，而非类别。

编写任何边界条目之前，请检查你匹配的内容是否属于 data/risk-paths.yml § false_positives。 其中每个条目都是这项技能在真实仓库中误判过的内容。误判比漏判更糟——它会让原本无需人工审核的合并也重新需要人工审核；而第一条明显错误的规则，会让读者觉得整个章节都只是猜测。

两个章节的模板，以及必须放在边界标题下方的定义行，见 references/agents-md.md § Generating the two sections。

评分： 只有在两个章节都存在、其中每一行都可由机器检查，且 ## Never merges without a human 包含定义行时，AGENTS.md 才算 Nailed It。缺少这两个章节的 AGENTS.md 属于 Could Be Better——它告诉 Agent 如何工作，却没有说明 Agent 可以自行完成什么。

---

Step 3 — 生成各工具的指针文件

为 Step 1d 检测到的每个工具生成一个简短指针，并默认生成 .github/copilot-instructions.md。

工具	文件
GitHub Copilot	.github/copilot-instructions.md
Claude Code	CLAUDE.md
Cursor	.cursorrules

指针内容共三行：

# Conventions

The conventions for this repository live in [`AGENTS.md`](<relative path>). Read that file first.

链接是相对于指针文件的路径，而非相对于仓库根目录：

指针文件	链接
.github/copilot-instructions.md	../AGENTS.md
CLAUDE.md、.cursorrules（仓库根目录）	./AGENTS.md
.github/instructions/*.instructions.md	../../AGENTS.md

Copilot 是唯一值得稍作扩展的例外。 Copilot 会自动将 .github/copilot-instructions.md 加载到上下文中，因此只有真正专属于 Copilot 的内容可以放在同一文件的指针行之后。绝不要重述 AGENTS.md 中已有的约定。

绝不重复。 如果现有工具文件重述了 AGENTS.md，不要悄悄改写——请在报告中将其标记为偏差，由用户决定（参见 Do No Harm）。

单体仓库： 为技术栈不同的区域创建 .github/instructions/{area-name}.instructions.md，并设置 applyTo 匹配模式。这些文件可以包含实际内容，因为它们按路径限定范围，不会重复根目录中的约定。

---

Step 4b — 生成 .mcp.json

如果仓库根目录下没有 .mcp.json，请根据检测到的依赖项（数据库、API、云平台、浏览器自动化、DevOps 工具）生成该文件。机密信息使用 ${VAR}。只包含项目实际需要的服务——不要臆测添加服务。

如果存在 .vscode/mcp.json，请将其标记为 “Could Be Better”，并建议迁移到 .mcp.json。

---

步骤 4c — 生成审查 Agent

如果缺少 .github/agents/，或其中没有审查 Agent，则生成一组入门级审查 Agent。 三个通常足以覆盖大多数仓库——spec-conformance、test-integrity、blast-radius——但数量应由仓库决定，而非遵循固定规则。 只生成其问题答案可能为否的 Agent：没有测试的仓库跳过 test-integrity；没有难以撤销的操作时跳过 blast-radius。说明跳过了什么以及原因。完整内容及添加方法见 references/reviewer-agents.md。

如果所用工具支持指定模型，请告诉用户将它们分配给不同模型。 使用同一个模型的审查 Agent 大多会遗漏相同的问题；同一模型上的三个 Agent，就像一个审查 Agent 配了三个提示词。

blast-radius 会读取步骤 2 中编写的 ## Never merges without a human 部分，从而将边界与实际运行的内容关联起来。

如果仓库已有覆盖这些关注点的 Agent，则保留它们，并指出其中的偏差。

---

步骤 4d — 根据维护矩阵生成入门技能

根据维护矩阵和 Adding a New [Feature/Module] 注册链生成 .github/skills/shipping-a-change/SKILL.md：

---
name: shipping-a-change
description: What to update when you change something in this repo, and what "done" requires. Use before opening a pull request.
---

# Shipping a change

## Add a new <thing this repo adds most often>
1. <real path> — create it
2. <real path> — register it
3. <real path> — export or declare it
4. <real command> — verify

## When you change this, also change that
| Change | Also update |
|---|---|
| <real path> | <real paths> |

## Done
<the `## Done means` list from AGENTS.md, verbatim>

使用真实路径和真实命令。 满是占位符的技能比没有技能更糟——它看起来权威，却毫无指导作用。

如果 .github/skills/ 中已有覆盖这些内容的技能，则指出其中的偏差。 如果维护矩阵内容单薄——少于三个真实的级联关系——则跳过生成并说明原因；只有一行的技能毫无价值。

---

步骤 4e — 仅在存在相关安全面时生成安全技能

不要生成通用安全技能。 “不要硬编码密钥”早已包含在每个模型的权重中——读起来像博客文章的安全技能比没有更糟，因为它会稀释这里真正重要的规则，让人们不再阅读。此步骤旨在记录本仓库特有、且其他地方没有的内容。

扫描安全面（参见 references/detection-tables.md § Security surface detection）。如果没有发现安全面，就不要生成技能——在报告中用一行说明，处理方式与步骤 4d 跳过内容单薄的维护矩阵相同。

如果发现安全面，则根据仓库的实际情况生成 .github/skills/security-review/SKILL.md。信息来源按优先级排序：

1. 已有的安全说明——SECURITY.md、AGENTS.md 中的检查清单、敏感代码附近的注释。通常这些内容已经存在——将它们移过来，不要另行编造。
2. 安全面本身——真实的处理程序、真实的信任边界，并用真实路径标明。
3. 有关安全的 PR 审查评论（步骤 0c）——如果审查者不断提出相同的安全问题，他们已经替你写好了技能。

待填充的框架见 references/detection-tables.md § Security surface detection。

每一行都必须指向本仓库中的真实内容。 如果某个部分只是在重述一般的最佳实践，就删掉它。

如果已有安全技能或 SECURITY.md，则提出迁移建议，并让用户决定。

---

步骤 5 — 生成 CI 工作流

如果不存在由 PR 触发的工作流，则创建 .github/workflows/ci.yml，包含：带有针对文档和配置的 paths-ignore 的 pull_request 和 push 触发器，以及与项目实际工具链相匹配的构建和测试任务。使用步骤 0b 检测到的默认分支——不要硬编码 main。切勿修改现有工作流。

---

步骤 6 — 生成问题模板和 PR 模板

如果缺少模板，则创建 Bug 报告和功能请求 YAML 表单，以及包含描述、变更、测试方法和检查清单（根据维护矩阵整理）的 PR 模板。将旧格式的 .md 模板标注为“可改进”。

步骤 7 — 更新 README 的贡献部分

如果 README 存在但没有贡献部分：如果 CONTRIBUTING.md 存在，则添加指向它的链接；否则，添加一个包含 fork、分支和 PR 说明以及测试命令的贡献部分。绝不要重写 README 的其余内容。

---

步骤 9 — 评估并改进变更日志

如果缺少 CHANGELOG.md，则按 Keep a Changelog 格式创建。如果是指针文件，则验证其指向的目标。如果内容过时，则标明日期。在 AGENTS.md 中记录非标准位置。

---

步骤 10 — 评估并改进文档

如果文档存在，则在 AGENTS.md 中记录其位置、框架和约定，而不是记录在不包含自身内容的指针文件中。如果文档缺失，则根据项目类型评估是否需要文档。始终在 AGENTS.md 中记录文档状态。

---

步骤 11 — 显示 AI 就绪度报告

使用 references/report-template.md 中的格式显示报告。在报告底部注明 frontmatter 中的 metadata.version 技能版本（例如，Assisted by ai-ready v1.0.0）。然后：

1. 添加 AI-Ready 徽章（参见 report-template.md § 11a）
2. 提出创建 PR（参见 report-template.md § 11b）

---

重要规则

不要造成损害

此技能的首要职责是让仓库的状态比发现时更好，而绝不更差。

• 绝不要创建重复文件 — 创建任何文件之前，检查所有已知位置（规范位置、旧位置和根目录）。如果某个文件已存在于任何位置，就不要再创建副本，而应进行整合。
• 绝不要直接推送到 main/master — 始终创建功能分支并发起 PR 供审核。唯一例外是用户明确要求提交到默认分支。
• 绝不要放任已开启的 PR — PR 开启且 CI 通过后，要么合并（改动较小、测试充分且没有需要主观判断的事项），要么询问用户如何处理；无论如何都要报告结果。如果 CI 未通过或仍在等待，不要合并；应修复问题、等待，或报告阻碍。
• 每当发生合并，都要使用 squash 合并，并随后删除分支 — 包括本地分支和远程分支。
• 绝不要覆盖现有文件 — 只创建缺失的资源。发现不一致时，标记出来供用户审核。
• 未经用户批准，绝不要删除文件 — 如果要整合重复文件或移除过时文件，应将删除操作纳入 PR 供审核。

一般规则

• 绝不要打开分页器 — 为每条 gh/git 命令追加 | cat。使用 git --no-pager。
• 始终显示完整报告 — 让用户了解发现和改动的全部情况。
• 绝不要在面向用户的输出中使用 Markdown 标题 — 使用粗体文本和表情符号。
• 始终在 issue/PR 沟通中提及 AI Ready 技能 — 在 issue 或 PR 中发帖（正文或评论）时，明确注明归属，例如 Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)。
• 始终按照仓库标准更新文档 — 生成的指导内容或工作流发生变化时，应更新本仓库维护矩阵所列的文档和变更日志。不要假设其他仓库中的文件在本仓库也存在。
• 始终主动处理 PR 冲突 — 创建 PR 时，与目标分支同步并尝试解决冲突；如果冲突仍未解决，明确询问用户希望如何处理。

---