/ai-ready

name: ai-ready
license: MIT
metadata:
  version: "1.4.0"
description: "**ANALYSIS SKILL** — Analyze any repository and generate AI-ready configuration — a canonical AGENTS.md, thin per-tool pointer files, skills, CI workflows, issue templates. WHEN: \"make this repo ai-ready\", \"set up AI config\", \"add copilot instructions\", \"prepare this repo for AI contributions\", \"generate AGENTS.md\". INVOKES: glob, grep, view, create, edit for repo analysis and file generation. FOR SINGLE OPERATIONS: use create/edit directly for individual config files."

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

| # | Asset | Generated in | |---|-------|-------------| | 1 | `AGENTS.md` | Step 2 | | 2 | Per-tool pointer files (`.github/copilot-instructions.md`, `CLAUDE.md`, …) | Step 3 | | 3 | Maintenance matrix (in `AGENTS.md`) | Step 2 | | 4 | Reviewer agents (`.github/agents/`) | Step 4c | | 5 | Starter skill (`.github/skills/`) | Step 4d | | 6 | Security skill (`.github/skills/`, when there is surface) | Step 4e |

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

| # | Asset | Generated in | |---|-------|-------------| | 7 | CI workflow (`.github/workflows/ci.yml`) | Step 5 | | 8 | Issue templates (`.github/ISSUE_TEMPLATE/`) | Step 6 | | 9 | PR template (`.github/PULL_REQUEST_TEMPLATE.md`) | Step 6 |

**📖 Onboarding** — what helps new contributors get started

| # | Asset | Generated in | |---|-------|-------------| | 10 | Changelog (`CHANGELOG.md`) | Step 9 | | 11 | Documentation (or explicit "not needed" note) | Step 10 |

**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](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](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](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 h