ai-ready

# AI-Ready Repo Skill

## Persona

Adopt the perspective of an experienced repo maintainer who has managed high-traffic repos and reviewed thousands of PRs. 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. The skill **never overwrites existing files without user approval**.

**Skipping assets:** If the user's prompt mentions skipping specific assets (e.g., "skip CI and issue templates"), 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 12 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 | `.github/copilot-instructions.md` | Step 3 |
| 3 | Maintenance matrix (in `copilot-instructions.md`) | Step 8 |
| 4 | `.mcp.json` | Step 4b |
| 5 | `.github/workflows/copilot-setup-steps.yml` | Step 4 |

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

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

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

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

**Scoring:** 🟩 Nailed It (counted) · 🟨 Could Be Better (not counted) · ⬜ Missing (not counted)

| Medal | Name | Count | What it means |
|-------|------|-------|---------------|
| 🥉 | **Getting Started** | 1–4 | Basics in place but AI agents are mostly guessing |
| 🥈 | **On Track** | 5–7 | AI agents can help but miss your conventions |
| 🥇 | **Solid** | 8–10 | AI agents follow your patterns and catch most expectations |
| 🏆 | **AI-Ready** | 11–12 | AI agents contribute like your best team members |

---

## Step 0 — Detect GitHub context automatically

**Zero user input required.** 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.

Key insight: **PR review mining is the highest-value step.** Repeated reviewer feedback becomes conventions in `copilot-instructions.md`.

---

## 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.

Key detections: lockfiles, runtime version files, monorepo markers, notebooks, VS Code extensions, multi-app collections, demo apps.

**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. Detect test setup

Identify test runner, find test directories (`tests/`, `__tests__/`, `spec/`, `e2e/`), extract test commands from scripts.

### 1c. Detect CI/CD

Check `.github/workflows/` for PR triggers. Check for other CI systems. Recognize community workflows (stale, welcome) as valid automation — not missing CI.

### 1d. Check existing AI configuration

Check for: `AGENTS.md`, `.github/copilot-instructions.md`, `.github/skills/`, `.github/agents/`, `.github/extensions/`, `.devcontainer/`.

**copilot-setup-steps.yml** — check ALL known locations: `.github/workflows/copilot-setup-steps.yml` (canonical), `.github/copilot-setup-steps.yml` (legacy), and repo root. If found in a non-canonical location, flag it for consolidation into `.github/workflows/` — do not create a duplicate.

If multiple instruction files exist, check for duplicates, contradictions, stale references, and scope clarity. See [references/detection-tables.md](references/detection-tables.md) for drift detection details.

### 1e. Check repo configuration

Check for: `CODEOWNERS`, `dependabot.yml`, issue templates, PR template, `LICENSE`, README Contributing section.

### 1f–1g. Evaluate changelog and documentation

Assess changelog health (exists, format, freshness). Assess docs (exists, framework, navigation, deploy pipeline, README linkage).

### 1h. Scan directory structure

List top-level directories and immediate children (skip `node_modules`, `.git`, `dist`, `build`, `target`, `vendor`).

### 1i. Compile findings

Produce a structured findings table combining GitHub context and code