AI Ready

AI-Ready Repo Skill

Persona

Adopt the perspective of an experienced repo maintainer. Prioritize what reduces review burden and contributor friction. Every file you generate should earn its place — generic boilerplate creates noise.

---

Follow these steps in order to analyze the current repository and generate all missing AI-ready configuration assets.

First run vs. re-run: On the first run, most assets will be missing — the skill creates them. On re-runs, it audits existing assets against the current codebase, checking for drift, stale content, and new conventions from recent PR reviews.

Skipping assets: If the user's prompt mentions skipping specific assets, respect those exclusions. Still run the full analysis, but skip generation for the excluded assets.

Report-only mode: If the user asks for a report without generating files (e.g., "how ai-ready is this repo?", "score this repo"), run the full analysis (Steps 0–1) and display the report (Step 11) — but skip all generation steps (Steps 2–10).

The 11 tracked assets

Assets are grouped into three categories. Count assets with Nailed It status for the score.

🤖 AI Context — what AI agents read to understand your repo

🔧 Dev Workflow — what keeps PRs clean and contributors on track

📖 Onboarding — what helps new contributors get started

Scoring: 🟩 Nailed It (counted) · 🟨 Could Be Better (not counted) · ⬜ Missing (not counted). Medals, the two prerequisites that cap them, and what the score may never claim are in references/report-template.md — read it in Step 11.

---

Step 0 — Detect GitHub context automatically

The skill is GitHub-native — it discovers everything from GitHub's tools.

0a. Identify the repo

Run git remote -v to extract the GitHub owner/repo. If not GitHub, fall back to local-only analysis.

0b–0d. Fetch metadata, mine PR reviews, check community health

Use GitHub MCP tools or gh CLI to auto-discover repo metadata, PR review patterns, and community health gaps. See references/github-discovery.md for the full API table, PR mining technique, and health gap mapping.

Repeated reviewer feedback — from humans and from review agents — becomes conventions in AGENTS.md. Weight recent patterns more heavily, and flag an abandoned one rather than resurrecting it as a current rule.

---

Step 1 — Analyze the codebase

GitHub context tells you what the repo is. Local analysis tells you how it works. Use glob, grep, and view combined with GitHub context from Step 0.

1a. Detect languages, frameworks, and repo type

Find manifest files and extract details. See references/detection-tables.md for the full manifest table, VS Code extension detection, multi-app collections, demo app patterns, and course/tutorial repo detection.

Course repos (3+ signals: numbered folders, lesson keywords, no primary app) adapt Steps 2–5. See detection-tables.md for the full signal list and step adaptations.

1b–1c. Detect test setup and CI

Community workflows (stale, welcome, labeler) are valid automation, not missing CI. Do not report a repo as having no CI because its only workflow is a stale-bot.

1d. Check existing AI configuration

Check for: AGENTS.md, .github/copilot-instructions.md, CLAUDE.md, .cursorrules, .cursor/rules/, .github/skills/, .github/agents/, .github/extensions/, .devcontainer/.

Two failure modes, and the second is the common one. AGENTS.md is canonical; every other instruction file should be a short pointer to it.

1. Duplication — a tool file restates conventions that also live in AGENTS.md. Flag as Could Be Better: duplicated guidance drifts silently, and then two agents work from two versions of the same standard.
2. Split — each file holds different content and neither is complete. This is what most repos actually have, and it is worse than duplication because nothing looks wrong. A tool reading only AGENTS.md never sees the conventions; a tool reading only the Copilot file never sees the build and test commands.

For a split, list specifically which sections exist in the tool file but not in AGENTS.md — those are what Step 2 needs to absorb. Do not rewrite the tool file here; propose the move and let the user decide.

1e–1h. Check configuration, changelog, docs, and structure

Detect CODEOWNERS, dependabot.yml, issue and PR templates, LICENSE, a README Contributing section, changelog health, and docs setup. Two judgments that are not obvious: a changelog may live in a docs site rather than CHANGELOG.md, so follow pointer files before reporting one missing; and freshness is measured against the latest git tag, not the file's date.

1i. Compile findings

Produce a structured findings table combining GitHub context and codebase analysis with file-path evidence. See references/detection-tables.md for the full findings table template.

List which of the 11 assets are missing. For existing assets, compare against analysis and flag drift as "Could Be Better."

1j. Detect monorepo areas

If workspace config found, list areas with name, path glob, and primary stack. For large library monorepos, map cross-package dependencies. See references/detection-tables.md for details.

---

Step 2 — Generate AGENTS.md

If missing, create AGENTS.md at the repo root. If it exists, compare against analysis and flag drift.

AGENTS.md is the canonical entry point for how this repo works — the one file every tool reads, and the one place a given convention is stated. That is not the same as putting everything in it. Read references/agents-md.md before generating: what belongs, what does not, and where the rest goes.

Two rules govern everything below.

1. The discoverability test. Before writing any section, ask: can the agent find this by reading the code? If yes, do not write it down. AGENTS.md is loaded before every task, so every line is paid for on every run and competes for attention with the actual work. Directory trees, tech-stack inventories and architecture summaries all fail this test — generate them only for what is genuinely surprising about this repo, and skip them entirely when the layout is conventional.

2. Put it at the narrowest scope that fits. Needed on every task → root AGENTS.md. Needed only in one area → a nested AGENTS.md in that directory, which is part of the standard and how monorepos are meant to scale (closest file wins). Needed only when doing one procedure → a skill (Step 4d). Lookup material → a linked doc.

Start at 20–30 lines — what agents most often get wrong in this repo — and grow only when a real mistake proves something is missing. 150 is a ceiling, not a target: past it, move something. This file gets worse as it gets longer, because a model follows roughly 150–200 instructions before adherence degrades and every line competes with the ones already there.

Generate these. They exist nowhere in the code, so they always pass the test:

• Build, test and run commands — buried in tooling config, needed on every task. Never hardcode versions; reference the manifest.
• Conventions that are not inferable — language, framework, test and style rules a reader could not derive from the code and its linter config. If the linter already enforces it, link the config instead of restating it.
• Conventions Mined from PR Reviews (Step 0c)
• Adding a New [Feature/Module] — the full registration chain: enums, index re-exports, config declarations. Nobody infers a registration chain by reading one file
• Common Pitfalls — what people get wrong here. This is experience, and it is not in the code
• Maintenance Matrix — what must be updated when each part of the codebase changes. Real file paths. Trace the actual dependency graph rather than stopping at top-level files: .csproj ProjectReferences, import chains, mod declarations, __init__.py re-exports. Keep it a table; Step 4d turns it into the procedure, so do not write the procedure here as well.

Do not generate these unless the repo makes them surprising: a project overview, a CI/CD section, a repository structure section, or a tech stack list. Each costs attention on every task and tells the agent something it can see.

A Key Patterns and Conventions heading is usually the conventions bullet above under a second name. Pick one.

Test Conventions — untestable claims. If the repo has more than one test lane — a fast mocked unit lane plus a slower one with real framework access, or unit plus integration plus e2e — add a rule telling agents not to take a pull request's "this can't be tested" at face value. Before agreeing, search the other lane for existing precedent of stubbing the exact API or state the new code depends on. A claim that is true for one lane is often false once another is checked, and "untestable" is the easiest way for a change to arrive with no coverage and nobody arguing.

Only generate this rule when multiple lanes actually exist — skip it for a single-lane setup, where it would be advice about a situation the repo doesn't have.

Two sections almost no repo has — generate both

Every line in both must be decidable by a machine with nobody interpreting it. A command that exits non-zero on failure passes the test. "Write clean code" does not.

## Done means — the conditions a change must meet before it is finished, derived from the repo's real commands.

## Never merges without a human — the boundary, seeded from the risk paths actually present in this repo and stated as paths or conditions rather than categories.

Before writing any boundary line, check what you matched against data/risk-paths.yml § false_positives. Every entry there is a line this skill got wrong in a real repo. A wrong entry is worse than a missing one — it puts a human back into merges that never needed one, and the first obviously-wrong line teaches the reader the section is guesswork.

Templates for both sections, and the definition line that must sit under the boundary heading, are in references/agents-md.md § Generating the two sections.

Scoring: AGENTS.md counts as Nailed It only when both sections are present, every line in them is machine-checkable, and ## Never merges without a human carries its definition line. An AGENTS.md without them is Could Be Better — it tells an agent how to work, but nothing about what it may finish on its own.

---