AGENTS.md git:20260917.5bccf0aA

Immutable. This exact content is served forever at /api/v1/blob/053884225c33422d.

# AI-Ready Repo — Agent Guide

This is an **Agent Skill** — not a traditional application. The deliverable is a skill definition
(`SKILL.md`) that teaches an AI coding agent how to make any repository AI-ready. There is nothing to compile
and nothing to ship a binary from.

There *is* code, though, and it has to pass before you push: a small Python validation harness under `tools/`
and `tests/` that checks the skill's detection data against fixture repos. See [§ Testing](#testing).

The skill follows the vendor-neutral [Agent Skills](https://agentskills.io) standard, so one canonical
`skills/ai-ready/SKILL.md` is consumed by GitHub Copilot, Claude Code, OpenAI Codex, and Cursor. Each tool gets
its own thin manifest that points at that same directory — **never duplicate the skill content.**

## Repository Structure

Conventional where you'd expect: `skills/ai-ready/` holds the skill, `docs/` the prose, `tests/` and `tools/`
the validation harness, `evals/` the manual rubric. Run `ls` for the rest.

The part that is **not** guessable, and that CI enforces:

**Six files carry a version and all six must agree** — `skills/ai-ready/SKILL.md` (`metadata.version`, the
source of truth), `plugin.json`, `.github/plugin/plugin.json`, `.claude-plugin/plugin.json`,
`.codex-plugin/plugin.json`, and `.claude-plugin/marketplace.json` (nested under `plugins[0]`). There is also
`.agents/plugins/marketplace.json`, which carries no version. Bumping one and not the rest is the most common
way to fail the build.

## Packaging Model

Distribution follows existing ecosystem conventions — **nothing bespoke**. The canonical
`skills/ai-ready/SKILL.md` follows the [Agent Skills](https://agentskills.io) standard, which is all the
[skills CLI](https://github.com/vercel-labs/skills) (`npx skills add`) needs to install into 70+ agents.

The native plugin manifests are additive, for users who prefer their tool's own plugin system. All of them
describe the **same** `skills/ai-ready/` directory. The repo root doubles as the plugin root, which is why no
manifest needs to copy or relocate skill content.

| File | Consumed by | How it finds the skill |
|---|---|---|
| *(none — convention)* | `npx skills add johnpapa/ai-ready` | scans `skills/*/SKILL.md` |
| `.github/plugin/plugin.json` | GitHub Copilot CLI | explicit `"skills": ["./skills/ai-ready"]` |
| `.claude-plugin/plugin.json` | Claude Code | convention — `skills/` in plugin root |
| `.claude-plugin/marketplace.json` | Claude Code `/plugin marketplace add` | plugin `source: "./"` |
| `.codex-plugin/plugin.json` | OpenAI Codex | explicit `"skills": "./skills/"` |
| `.agents/plugins/marketplace.json` | Codex `plugin marketplace add` | plugin `source.path: "./"` |
| `plugin.json` | Cursor and Agent Plugins clients | convention — `skills/` in plugin root |
| `skills.sh.json` | skills.sh registry page | groups skills for display |

The `version` field must be identical in all five plugin manifests and in `SKILL.md` frontmatter
`metadata.version`. CI enforces this.

## Tech Stack

- **Content format:** Markdown, YAML, JSON — this is a documentation-driven project
- **No build system and nothing to compile.** The repo ships files agents read directly
- **Validation harness:** Python 3 with `pyyaml`, under `tools/` and `tests/`. Dependency-free otherwise — no
  framework, no test runner. `tests/test_detection.py` is a plain script that exits non-zero

## Build & Run

There is no build step. This repo ships markdown, YAML and JSON files that agents read directly.

Before pushing, run what CI runs:

```bash
pip install pyyaml
python3 tests/test_detection.py               # risk-path globs against fixtures
python3 tools/gen_detection_tables.py --check # generated tables match their data
```

**To test the skill locally in every installed tool:**

```bash
npx skills add ./ --agent claude-code codex cursor
```

That installs `skills/ai-ready/` into each tool, so edits take effect on the next agent restart. Then
start your agent and invoke the skill:

```
make this repo ai-ready
```

Use `npx skills add ./ --list` to confirm the skill is discoverable without installing it, and
`npx skills remove ai-ready` to clean up. **Native plugin installs** are documented in `README.md`.

## Testing

Run these before you push — they are what CI runs:

```bash
pip install pyyaml
python3 tests/test_detection.py                  # risk-path globs against tests/fixtures/
python3 tools/gen_detection_tables.py --check    # generated tables match their data
npx -y skills@latest add ./ --list               # the skill is discoverable
```

CI additionally checks `SKILL.md` frontmatter, YAML syntax across `.github/`, version parity across the six
files above, Agent Skills spec compliance, and `skills.sh.json` parity. Full table in
[docs/authoring.md](docs/authoring.md).

`skills/ai-ready/data/risk-paths.yml` is the **source of truth** for detection; the table in
`references/detection-tables.md` is generated from it and CI fails on drift. Edit the YAML, run the generator,
commit both. When you fix a bad detection, add the case to a fixture in the same PR.

**CI validates packaging and detection data — not the skill's judgment.** Every check passes on a `SKILL.md`
whose instructions are wrong. That gap is what [`evals/`](evals/) is for, and why the PR template asks which
repo you ran against. See [docs/authoring.md](docs/authoring.md) before changing skill behavior.

## Key Patterns and Conventions

- **Skills live in `skills/<name>/SKILL.md`** — each skill is a markdown file with YAML frontmatter (`name`, `description`) and step-by-step instructions
- **The skill is self-sufficient** — it uses Copilot's built-in tools (glob, grep, view, create) to analyze repos and generate files. No custom extensions or code required
- **Never overwrite existing files** — the skill checks for existing assets before generating
- **Issue/PR provenance is required** — issue and PR communication produced by this skill must explicitly mention AI Ready (for example: `Assisted by [ai-ready](https://github.com/johnpapa/ai-ready)`)
- **Docs must stay in sync** — when skill behavior changes, update `README.md`, `docs/how-it-works.md`, and `CHANGELOG.md` to match repo standards
- **PR conflicts must be addressed** — when opening PRs, attempt conflict resolution first; if unresolved, ask for user direction

## Writing Conventions

### Markdown

- Use ATX-style headings (`#`, `##`, `###`)
- Use fenced code blocks with language identifiers (```yaml, ```bash, ```json)
- Use tables for structured data — always include a header row
- Keep lines under 120 characters where practical
- Use `**bold**` for emphasis, `_italic_` for terms, `` `backticks` `` for file paths and commands

### YAML (skill frontmatter, workflows, issue templates)

- Use 2-space indentation
- Quote strings that contain special YAML characters
- Always include `name` and `description` in skill frontmatter

### JSON

- Use 2-space indentation

## Skill Writing Conventions

- Each step should be independently actionable — executable without context from other steps
- Include explicit "check if exists" guards before creating files
- Use real file paths and real commands, not placeholders
- Prefer structured output (tables) over prose for analysis results
- Always end with a summary step listing what was created, skipped, and what to do next

`SKILL.md` targets **under 500 lines** and `AGENTS.md` targets **~150** — both because they are loaded on every
invocation. Why, the sources, and what to do when you hit them: [docs/authoring.md](docs/authoring.md).

## Maintenance Matrix

| When this changes... | Also update... |
|---|---|
| `skills/ai-ready/SKILL.md` | `README.md` (if skill behavior changed), `docs/how-it-works.md`, `AGENTS.md`, `CHANGELOG.md` |
| `SKILL.md` past ~500 lines, or `AGENTS.md` past ~150 | Move narrow-scope content out — `references/` for the skill, `docs/` or a nested `AGENTS.md` for this file. See [docs/authoring.md](docs/authoring.md). Never cut something load-bearing to hit a number |
| `.github/workflows/ci.yml` | The check list in [docs/authoring.md](docs/authoring.md) § The full CI picture, and the CI summary in `README.md` § Contributing |
| `skills/ai-ready/references/*` | Verify consistency with `SKILL.md` steps that reference them |
| New skill added to `skills/` | `README.md`, `AGENTS.md` (structure section), `CHANGELOG.md` |
| `docs/how-it-works.md` | Verify consistency with `SKILL.md` steps and `README.md` |
| `README.md` problem statement or architecture | Verify consistency with `docs/how-it-works.md` |
| Repo structure changes (new dirs, moved files) | `AGENTS.md` (structure section), `CHANGELOG.md` |
| Version bump (`SKILL.md` metadata) | **All** manifests — `.github/plugin/plugin.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, root `plugin.json` — plus `CHANGELOG.md` and GitHub Release |
| Any plugin manifest | Keep `version` identical across all manifests and `SKILL.md`; CI fails on drift |
| `skills.sh.json` | Must list every directory under `skills/`; CI fails on drift |
| New tool/platform supported | `README.md` install table, `AGENTS.md` (packaging model); add a manifest only if the tool cannot use `npx skills` |
| `skills/ai-ready/data/*.yml` | Run `python3 tools/gen_detection_tables.py` and commit the regenerated `references/detection-tables.md`; add or update a fixture in `tests/fixtures/` covering the change |
| A detection bug found in a real repo | Add the case to a fixture in `tests/fixtures/` in the same PR, and add the pattern to `false_positives` in `data/risk-paths.yml` if it is one |
| `evals/rubric.md` | `evals/results/TEMPLATE.md` if the sections changed; previous results keep their original rubric version |
| Scoring, medals, or the tracked asset list | `SKILL.md` (asset table + medal table), `references/report-template.md` (square count, category indicators, cap wording), `README.md` § Scoring, `docs/how-it-works.md`, `CHANGELOG.md` |

## Common Pitfalls

- **Don't add build/test/runtime dependencies** — this is a markdown-only project. Agents should not invent `npm install`, `pip install`, or any setup commands for this repo
- **SKILL.md frontmatter is required** — the `name` and `description` fields in the YAML frontmatter are how agents discover and match the skill to user requests. Keep frontmatter to the portable Agent Skills fields (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`); vendor-specific keys break portability
- **Never duplicate skill content per tool** — every manifest points at the one canonical `skills/ai-ready/`. Copying it would guarantee drift
- **Bump the version in all five manifests** — `SKILL.md`, `.github/plugin/plugin.json`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, and root `plugin.json`. CI fails otherwise
- **Test on real repos** — the only meaningful test is invoking the skill on different repo types (Node.js, Python, Go, Rust, etc.) and verifying the output