Agent-Ready
Overview
A repo is agent-ready when an agent can navigate it, understand the slice it needs, and verify its own work, without ingesting the whole tree. The organizing principle is progressive disclosure: lean entry points that point to deeper detail, loaded only on demand. Every dimension below serves that principle.
Agents fail in repos for predictable reasons: they can't find entry points, don't know the rules so they guess, read huge files to answer small questions, can't tell live code from dead, and have no fast feedback loop. Agent-ready closes those gaps and keeps them closed.
When to use
- Asked to make a repo agent-ready / agent-optimized, or audit one.
- Bootstrapping or refreshing
CLAUDE.md / AGENTS.md.
- A SessionStart notice reports missing or stale context files.
- A file has outgrown the line budget.
Not for building application features. For a large structural change (carving a subsystem, swapping a dependency), this skill defers to ddd:domain-driven-design rather than duplicating it.
How to run an audit (progressive disclosure in practice)
Do not read all seven references up front. Cheap scan first, then drill only into what flagged.
- Cheap scan: cheaply detect which dimensions have issues:
ls the root for CLAUDE.md/AGENTS.md, list files over the budget (git ls-files | xargs wc -l), check for a documented build/test command, skim the top-level layout.
- Drill in: for each dimension that flagged, read its reference (below) and apply its checks.
- Report: produce a prioritized remediation list, highest leverage first (context files usually win).
- Safe-fix: apply only the safe class automatically (see policy). Everything else is reported for the human.
The seven dimensions
Each links to its reference. Load a reference only when that dimension flagged.
- Progressive disclosure: layered docs, agent loads only its slice.
references/progressive-disclosure.md
- Context files:
CLAUDE.md + AGENTS.md, current, concise, kept in sync. references/context-files.md
- File focus: files within a line budget; oversized files split.
references/file-focus.md
- Boundaries & navigability: clear structure, discoverable entry points.
references/boundaries.md
- Verification: one documented command an agent runs to self-verify.
references/verification.md
- Ambiguity & redundancy: dead code, duplicate concepts, contradicting docs.
references/ambiguity.md
- Discoverability: README, dir-level docs, self-explaining scripts.
references/discoverability.md
Safe-fix policy
| Class |
Action |
Regenerate / sync CLAUDE.md + AGENTS.md |
Auto-fix |
| Fix stale doc links, dead references in docs |
Auto-fix |
Add a make help / document the verify command |
Auto-fix |
| Flag dead code (with evidence) |
Report, don't delete |
| Split an oversized file |
Report (or hand to ddd if it's a boundary change) |
| Restructure modules / move packages |
Report, defer to ddd |
Never delete code or move files automatically. Surface those with a recommendation and let the human decide.
Relationship to the rest of the plugin
- The
/agent-ready command runs this audit on demand and applies the safe-fix class.
- The plugin's hooks enforce two dimensions continuously: a PreToolUse line-budget check (dimension 3) and a SessionStart context-drift check (dimension 2). Thresholds live in
.claude/agent-ready.local.md.
1---2name: agent-ready3description: Use when making a repository easy for coding agents to work in, or keeping it that way, auditing a repo for agent ergonomics, bootstrapping or refreshing CLAUDE.md / AGENTS.md, when a session-start notice says context files are missing or stale, when a file has grown too large for an agent to hold in context, or when onboarding a codebase for agentic development. Not for writing application features.4---56# Agent-Ready78## Overview910A repo is agent-ready when an agent can navigate it, understand the slice it needs, and verify its own work, without ingesting the whole tree. The organizing principle is **progressive disclosure**: lean entry points that point to deeper detail, loaded only on demand. Every dimension below serves that principle.1112Agents fail in repos for predictable reasons: they can't find entry points, don't know the rules so they guess, read huge files to answer small questions, can't tell live code from dead, and have no fast feedback loop. Agent-ready closes those gaps and keeps them closed.1314## When to use1516- Asked to make a repo agent-ready / agent-optimized, or audit one.17- Bootstrapping or refreshing `CLAUDE.md` / `AGENTS.md`.18- A SessionStart notice reports missing or stale context files.19- A file has outgrown the line budget.2021Not for building application features. For a large structural change (carving a subsystem, swapping a dependency), this skill **defers to `ddd:domain-driven-design`** rather than duplicating it.2223## How to run an audit (progressive disclosure in practice)2425Do not read all seven references up front. Cheap scan first, then drill only into what flagged.26271. **Cheap scan**: cheaply detect which dimensions have issues: `ls` the root for `CLAUDE.md`/`AGENTS.md`, list files over the budget (`git ls-files | xargs wc -l`), check for a documented build/test command, skim the top-level layout.282. **Drill in**: for each dimension that flagged, read its reference (below) and apply its checks.293. **Report**: produce a prioritized remediation list, highest leverage first (context files usually win).304. **Safe-fix**: apply only the safe class automatically (see policy). Everything else is reported for the human.3132## The seven dimensions3334Each links to its reference. Load a reference only when that dimension flagged.35361. **Progressive disclosure**: layered docs, agent loads only its slice. `references/progressive-disclosure.md`372. **Context files**: `CLAUDE.md` + `AGENTS.md`, current, concise, kept in sync. `references/context-files.md`383. **File focus**: files within a line budget; oversized files split. `references/file-focus.md`394. **Boundaries & navigability**: clear structure, discoverable entry points. `references/boundaries.md`405. **Verification**: one documented command an agent runs to self-verify. `references/verification.md`416. **Ambiguity & redundancy**: dead code, duplicate concepts, contradicting docs. `references/ambiguity.md`427. **Discoverability**: README, dir-level docs, self-explaining scripts. `references/discoverability.md`4344## Safe-fix policy4546| Class | Action |47|-------|--------|48| Regenerate / sync `CLAUDE.md` + `AGENTS.md` | Auto-fix |49| Fix stale doc links, dead references in docs | Auto-fix |50| Add a `make help` / document the verify command | Auto-fix |51| Flag dead code (with evidence) | Report, don't delete |52| Split an oversized file | Report (or hand to `ddd` if it's a boundary change) |53| Restructure modules / move packages | Report, defer to `ddd` |5455Never delete code or move files automatically. Surface those with a recommendation and let the human decide.5657## Relationship to the rest of the plugin5859- The `/agent-ready` command runs this audit on demand and applies the safe-fix class.60- The plugin's hooks enforce two dimensions continuously: a PreToolUse line-budget check (dimension 3) and a SessionStart context-drift check (dimension 2). Thresholds live in `.claude/agent-ready.local.md`.
guygrigsby