Agent-Ready
Onboard coding agents like new engineers.
Before you hand a coding agent tickets, give it the repo context a human engineer would need: how the system is shaped, what commands verify changes, where domain knowledge lives, and which decisions are already settled.
agent-ready is a free skill that analyzes your repository and scaffolds a progressive-disclosure documentation set agents can use before they code.
codebase-readiness scores the repo. agent-ready builds the first documentation layer.
Definition
What Is Agent-Ready?
An agent-ready repository gives coding agents the same orientation a new engineer needs before making changes. It names the project conventions, architecture boundaries, domain language, verification commands, and decision history in files agents can discover and follow.
Install
Get the Skill
agent-ready is an agent skill. Enter your email and I'll send you both ways to install it, how to run it, and how it picks a mode from your codebase-readiness assessment.
Send me the skill
I'll send the install instructions to your inbox. You'll also get practical notes on AI engineering and agent architecture. No spam. Unsubscribe anytime.
The output is a starting point, not a substitute for human review. The domain file is especially valuable once someone close to the product fills in the gaps.
Output
What It Creates
The scaffold follows progressive disclosure: a short entry point for the agent, deeper files for architecture, domain, guides, references, and decisions.
01
AGENTS.md
The canonical agent entry point: project identity, key commands, documentation map, operating rules, and definition of done.
02
CLAUDE.md symlink
Backward compatibility for Claude Code while keeping AGENTS.md as the single source of truth.
03
ARCHITECTURE.md
A repo codemap that names important modules, boundaries, invariants, entry points, and deliberate absences.
04
docs/README.md
A documentation index so humans and agents know where project knowledge lives.
05
docs/DOMAIN.md
A seeded business-domain glossary, workflow map, and terminology file for context that rarely lives in code.
06
Starter ADR
docs/decisions/001-agent-ready-documentation.md records why the repo adopted this structure.
Mechanics
How the Skill Works
- 01
Inventory the repo
Detects language, framework, commands, existing docs, CI, ADRs, and current AGENTS.md or CLAUDE.md files.
- 02
Generate from actual structure
Builds the scaffold from discovered files and conventions instead of dropping in a generic template.
- 03
Keep context layered
Keeps AGENTS.md concise and points to deeper files when the agent needs architecture, domain, setup, or decision context.
- 04
Leave review points visible
Marks domain and product assumptions for human review so the repo gets better over time instead of fossilizing a first draft.
Workflow
How Do You Make a Repo Agent-Ready for Coding Agents?
The practical workflow is simple: assess the repo, scaffold the missing context, review the generated docs, and rerun the assessment after the documentation layer is in place.
- 01
Run codebase-readiness if you do not already know the weakest dimensions.
- 02
Run agent-ready to create AGENTS.md, ARCHITECTURE.md, docs/DOMAIN.md, docs/README.md, and a starter ADR.
- 03
Review docs/DOMAIN.md with someone close to the product so agent assumptions match the real business.
- 04
Use the generated AGENTS.md as the agent entry point and keep detailed context in linked docs.
- 05
Rerun codebase-readiness after the scaffold to see what gaps remain.
When to use it
When to Use It
- A repo has no AGENTS.md, CLAUDE.md, ARCHITECTURE.md, or ADR structure yet.
- Your coding agent keeps missing local conventions, whether you use Codex, Claude Code, Cursor, or something else.
- A new team member would need a walkthrough before making a safe change.
- Your codebase-readiness score shows weak Documentation & Context or Architecture Clarity.
- You want a repeatable onboarding package before giving agents larger tasks.
Modes
Modes
Use the full scaffold when the repo needs a baseline. Use narrower modes when you already have part of the system.
scaffold
Full documentation setup: docs/ structure, ARCHITECTURE.md, AGENTS.md, CLAUDE.md symlink, and starter ADR.
architecture
Generate or refresh ARCHITECTURE.md from real codebase analysis.
agents-md
Create or refactor AGENTS.md for progressive disclosure and Claude Code compatibility.
audit
Check existing agent docs for staleness, broken links, overlap, and missing coverage.
Source
Source
The skill is part of my public claude-code-workflows repository. Install instructions arrive by email when you request the skill above.
Writing
Related Writing
Background on why repo context changes agent output quality.
- ArticleFour Dimensions of Agent-Ready Codebase DesignThe principles behind agent-facing entry points, codemaps, feedback loops, and codebase structure.
- ArticleHow I Use Claude Code: My Complete Development WorkflowThe workflow this skill grew out of: repo-local instructions, skills, and repeatable development loops.
- ArticleMCPs vs Agent SkillsHow skills differ from tools, and why some workflow knowledge belongs in repo-local instructions.
FAQ
Frequently Asked Questions
Is this the same as codebase-readiness?
No. codebase-readiness scores the repo and produces a prioritized roadmap. agent-ready scaffolds the documentation layer that closes common Documentation & Context and Architecture Clarity gaps.
Does it replace writing good docs?
No. It creates the first useful structure. Humans still need to review the domain file, tighten architectural claims, and keep decisions current.
Why AGENTS.md instead of CLAUDE.md?
AGENTS.md is the broader convention for agent-facing repo instructions. The skill also creates CLAUDE.md as a symlink so Claude Code gets the same instructions without creating a second source of truth.
Will it change application code?
No. The scaffold focuses on documentation and repo context: AGENTS.md, ARCHITECTURE.md, docs/ files, and ADRs.
When should I run the assessment first?
Run codebase-readiness first when you do not know whether documentation is the real bottleneck. It will show whether the bigger gap is context, tests, architecture, feedback loops, or something else.
How do I make a repo agent-ready for coding agents?
Start with an assessment if the gaps are unclear, then scaffold AGENTS.md, ARCHITECTURE.md, docs/DOMAIN.md, docs/README.md, and a starter ADR. Review the generated domain and architecture context before giving agents larger tasks.
Make the repo legible before asking agents to change it.
Start with the self-serve scaffold. If the assessment shows deeper gaps across tests, architecture, or team workflow, that is where a Foundation Sprint or retainer is a better fit.