Agent Skills: Agent-Ready

Agent-Ready

Scaffold the documentation and structural artifacts that make a codebase legible to AI agents. This skill is the remediation companion to codebase-readiness -- it does not score, it builds.

Startup: Check for Prior Assessment

Before entering any mode, check if AGENT_READY_ASSESSMENT.md exists in the project root.

If it exists:

1. Read it and extract dimension scores
2. Auto-suggest a mode based on the weakest dimensions:
   • Documentation & Context < 50 -> suggest claude-md first
   • Architecture Clarity < 50 -> suggest architecture first
   • Both < 50 -> suggest scaffold (full setup)
3. Tell the user: "I found an existing assessment. Based on your scores, I recommend starting with [mode]. Want to proceed, or choose a different mode?"

If it does not exist, proceed with mode detection.

Mode Detection

Determine which mode to run based on user intent:

| User Intent | Mode | Trigger Phrases | |-------------|------|-----------------| | Full documentation setup | scaffold | "make this agent-ready", "full setup", "scaffold docs" | | Generate architecture doc | architecture | "create ARCHITECTURE.md", "architecture doc", "codemap" | | Create/refactor AGENTS.md | agents-md | "set up AGENTS.md", "create AGENTS.md", "refactor AGENTS.md" | | Check existing artifacts | audit | "audit docs", "are my docs up to date", "check agent readiness" |

If intent is ambiguous, ask the user which mode they want.

Mode: scaffold

Full documentation setup. This is the comprehensive mode that creates everything a codebase needs for agent legibility.

Step 1: Reconnaissance

Gather project metadata:

# Language and framework detection
ls package.json Gemfile requirements*.txt pyproject.toml go.mod Cargo.toml build.sbt pom.xml *.csproj 2>/dev/null

# Directory structure
find . -maxdepth 3 -type d 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | grep -v ".bundle" | grep -v __pycache__ | sort | head -50

# Existing documentation
find . -maxdepth 2 -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "ARCHITECTURE.md" -o -name "README.md" -o -name "CONTRIBUTING.md" 2>/dev/null | grep -v node_modules | grep -v .git
ls -la docs/ doc/ 2>/dev/null
find docs/ doc/ -name "*.md" 2>/dev/null | head -20

# Build/test/lint commands
cat package.json 2>/dev/null | grep -A5 '"scripts"'
cat Makefile 2>/dev/null | grep -E "^[a-zA-Z_-]+:" | head -10
cat Rakefile 2>/dev/null | head -20
ls .eslintrc* .rubocop.yml .prettierrc* pyproject.toml ruff.toml .golangci.yml 2>/dev/null

# CI configuration
ls .github/workflows/*.yml .circleci/config.yml .buildkite/*.yml Jenkinsfile 2>/dev/null

# ADRs
find . -type d -name "decisions" -o -name "adr" -o -name "adrs" 2>/dev/null | grep -v node_modules | grep -v .git

Step 2: Report Inventory

Present a clear inventory to the user:

## Documentation Inventory

### Exists
- [List each existing artifact with path and line count]

### Missing
- [List each missing artifact that will be created]

### Will Create
- docs/ directory structure
- docs/README.md (documentation index)
- ARCHITECTURE.md (codemap, invariants, boundaries)
- docs/DOMAIN.md (business domain knowledge, terminology, workflows)
- AGENTS.md (progressive disclosure entry point)
- CLAUDE.md (symlink to AGENTS.md for Claude Code compatibility)
- docs/decisions/001-agent-ready-documentation.md (starter ADR)

Step 3: Create docs/ Structure

Read assets/docs-structure-template.md for the recommended layout.

Create the directory structure:

mkdir -p docs/architecture docs/guides docs/references docs/decisions

Create docs/README.md as an index. Populate it based on what documentation exists and what will be created.

Step 4: Generate ARCHITECTURE.md

Execute the architecture mode logic (see below) inline. Do not launch a separate agent.

Step 5: Generate docs/DOMAIN.md

Read assets/domain-knowledge-template.md for the template.

Seed the template by scanning the codebase:

# Find model/entity/type names
find . -type f \( -name "*.rb" -o -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.go" -o -name "*.java" \) 2>/dev/null \
  | grep -v node_modules | grep -v .git | grep -v vendor \
  | xargs grep -lE "class |model |entity |type |interface |struct " 2>/dev/null | head -20

# Look for model directories
find . -type d \( -name "models" -o -name "entities" -o -name "types" -o -name "schemas" -o -name "domain" \) 2>/dev/null \
  | grep -v node_modules | grep -v .git | grep -v vendor

# Read README for business context
cat README.md 2>/dev/null | head -80

Using the discovered model/entity names and README context:

1. Populate the glossary with discovered terms, even if definitions are thin -- mark them with <!-- TODO: needs domain expert review -->
2. Sketch domain relationships based on model associations or naming patterns
3. Leave workflow and regulatory sections as template placeholders if not enough context exists

Write the result to docs/DOMAIN.md. Note in the output that this file should be reviewed and filled in by domain experts on the team -- it is seeded from code analysis and will have gaps.

Step 6: Generate AGENTS.md

Execute the agents-md mode logic (see below) inline. Do not launch a separate agent.

Step 7: Create Starter ADR

Create docs/decisions/001-agent-ready-documentation.md:

# 1. Agent-Ready Documentation Structure

**Date:** [today's date]
**Status:** Accepted

## Context
This codebase is being prepared for AI agent work. Agents need structured, discoverable documentation to work effectively -- they cannot access knowledge that lives outside the repository.

## Decision
Adopt a progressive disclosure documentation structure:
- AGENTS.md as a concise entry point (~100 lines) with markdown links to detailed docs
- CLAUDE.md as a symlink to AGENTS.md for Claude Code compatibility
- ARCHITECTURE.md as a codemap with invariants and boundaries
- docs/DOMAIN.md for business domain knowledge, terminology, and workflows
- docs/ directory for guides, references, and decision records
- Nested AGENTS.md files for major domain directories (as needed)

## Consequences
- All project knowledge must live in-repo (not in Slack, Confluence, or heads)
- Documentation changes should be reviewed like code changes
- AGENTS.md must stay concise; bloat gets extracted to docs/
- ADRs should be written for significant architectural decisions going forward

## Alternatives Considered
- Single large AGENTS.md -- rejected because it crowds agent context and rots quickly
- No structured docs, rely on code comments -- rejected because agents need navigational aids beyond inline comments

Step 8: Summary

Present everything created with file paths, and suggest next steps:

• Review docs/DOMAIN.md and add business domain definitions -- this is the most valuable file for human and AI onboarding
• Add domain-specific nested AGENTS.md files for major directories
• Start writing ADRs for future architectural decisions
• Set up CI checks for documentation freshness
• Run agent-ready audit periodically to check for drift

Mode: architecture

Generate an ARCHITECTURE.md from actual codebase analysis.

Step 1: Map the Codebase

# Top-level structure
find . -maxdepth 2 -type d 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | grep -v ".bundle" | grep -v __pycache__ | sort

# Identify major modules and entry points
find . -maxdepth 2 -type f -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.scala" 2>/dev/null | grep -v node_modules | grep -v .git | grep -v vendor | head -50

# Entry points
ls src/index.* src/main.* app/main.* main.* cmd/ 2>/dev/null
ls config/ 2>/dev/null

# Largest files (potential god objects)
find . -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.py" -o -name "*.go" -o -name "*.java" 2>/dev/null \
  | grep -v node_modules | grep -v .git | grep -v vendor | grep -v spec | grep -v test \
  | xargs wc -l 2>/dev/null | sort -rn | head -15

Step 2: Detect Patterns

Read source files to identify:

• Layers: controllers/handlers, services, repositories/models, utilities
• Domains: distinct business domains grouped in the filesystem
• Entry points: where the application starts, what the main interfaces are
• Configuration: how the app is configured, environment handling
• Cross-cutting: logging, auth, error handling, middleware

Step 3: Read Existing Context

Read README.md and any existing documentation for project context. Do not duplicate what README already covers -- ARCHITECTURE.md complements it.

Step 4: Load References

Read references/architecture-guide.md for matklad's principles. Read assets/architecture-md-template.md for the output template.

Step 5: Generate ARCHITECTURE.md

Using the template and principles, generate an ARCHITECTURE.md with:

• Overview: One paragraph describing the problem domain (not the tech stack)
• Codemap: Every significant top-level directory with one-line descriptions. Name important files and types.
• Invariants: Rules that hold across the codebase. Always include absences -- things that deliberately do not exist.
• Boundaries: Public vs internal APIs. Layer dependency rules. Which modules can import which.
• Cross-cutting concerns: How logging, auth, errors, and config work across the system.

Step 6: Present and Confirm

Show the draft to the user. Write to ARCHITECTURE.md in the project root on confirmation.

Mode: agents-md

Create a new AGENTS.md or refactor an existing one for progressive disclosure. Also creates CLAUDE.md as a symlink for Claude Code compatibility.

Step 1: Assess Current State

Check if AGENTS.md or CLAUDE.md exists:

find . -name "AGENTS.md" -o -name "CLAUDE.md" 2>/dev/null | grep -v node_modules | grep -v .git

If AGENTS.md exists, analyze it:

wc -l AGENTS.md
# Code block percentage
echo "Code block lines: $(sed -n '/^```/,/^```/p' AGENTS.md | wc -l)"
# Directive density
echo "Directive keywords: $(grep -ci 'must\|never\|always\|avoid\|prefer' AGENTS.md)"
# Doc links
echo "Doc links: $(grep -coE '\[.*\]\([^)]+\.md\)' AGENTS.md)"
# Section count
echo "Sections: $(grep -c '^##' AGENTS.md)"

Read the existing AGENTS.md fully. Identify:

• Sections that are bloated (>30 lines on one topic)
• Code examples that are too long (>10 lines)
• Content that belongs in topic docs, not AGENTS.md
• Missing directives (build, test, lint commands)
• Missing links to supporting docs

If CLAUDE.md exists but not AGENTS.md, analyze CLAUDE.md the same way and plan to migrate it to AGENTS.md.

If neither exists, proceed to generation.

Step 2: Load References

Read references/progressive-disclosure.md for Harness Engineering principles. Read assets/claude-md-template.md for the output template (note: template is called claude-md-template but generates AGENTS.md content).

Step 3: Detect Project Signals

Gather the information needed to populate AGENTS.md:

# Build/test/lint commands
cat package.json 2>/dev/null | grep -A10 '"scripts"'
cat Makefile 2>/dev/null | grep -E "^[a-zA-Z_-]+:" | head -10
ls .eslintrc* .rubocop.yml .prettierrc* ruff.toml .golangci.yml 2>/dev/null

# CI config (for workflow hints)
ls .github/workflows/*.yml 2>/dev/null

# Existing docs to link
find docs/ doc/ -name "*.md" 2>/dev/null | head -20
ls ARCHITECTURE.md CONTRIBUTING.md 2>/dev/null

# ADRs (check if decision records exist)
find . -path "*/decisions/*.md" -o -path "*/adr/*.md" -o -path "*/adrs/*.md" 2>/dev/null | grep -v node_modules | grep -v .git | head -5

Step 4: Generate or Refactor

New AGENTS.md: Using the template, generate an AGENTS.md that:

• Stays under ~100 lines
• Leads with project identity and build/test/lint one-liners
• Uses directives (must/never/always/avoid/prefer) for conventions
• Markdown links to existing docs or docs that should be created
• Includes ADR section if docs/decisions/ or other ADR directories exist
• Lists max 5 known gotchas
• Avoids code examples longer than 5 lines

Refactoring existing AGENTS.md or migrating from CLAUDE.md:

1. Identify bloated sections
2. Extract content to appropriate docs/ files (create them)
3. Replace extracted content with markdown links
4. Tighten language to directives
5. Present before/after comparison showing:
   • Line count reduction
   • Content moved to which files
   • New doc links added

Step 5: Create Symlink

After creating or updating AGENTS.md, create a symlink from CLAUDE.md to AGENTS.md for Claude Code compatibility:

# Remove CLAUDE.md if it exists and is a regular file (not already a symlink)
if [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  # If CLAUDE.md exists and AGENTS.md doesn't exist yet, this was already migrated in step 4
  # Otherwise, back it up first
  if [ ! -f AGENTS.md ]; then
    echo "CLAUDE.md will be migrated to AGENTS.md"
  else
    echo "Backing up existing CLAUDE.md to CLAUDE.md.backup before creating symlink"
    mv CLAUDE.md CLAUDE.md.backup
  fi
fi

# Create the symlink
ln -sf AGENTS.md CLAUDE.md

# Verify the symlink
ls -la CLAUDE.md

Inform the user that:

• AGENTS.md is the canonical documentation file that works with any AI coding agent
• CLAUDE.md is a symlink to AGENTS.md for backward compatibility with Claude Code
• Both files now point to the same content

Step 6: Present and Confirm

Show the draft (or before/after diff for refactoring). Write AGENTS.md and create the CLAUDE.md symlink on confirmation.

Mode: audit

Check health of existing agent-readiness artifacts.

Step 1: Inventory

Find all agent-readiness artifacts:

# AGENTS.md and CLAUDE.md files (root and nested)
find . -name "AGENTS.md" -o -name "CLAUDE.md" 2>/dev/null | grep -v node_modules | grep -v .git

# Check if CLAUDE.md is a symlink to AGENTS.md
if [ -L CLAUDE.md ]; then
  echo "CLAUDE.md is a symlink to: $(readlink CLAUDE.md)"
fi

# ARCHITECTURE.md
find . -name "ARCHITECTURE.md" 2>/dev/null | grep -v node_modules | grep -v .git

# docs/ contents
find docs/ doc/ -type f 2>/dev/null | grep -v node_modules | grep -v .git

# ADRs
find . -path "*/decisions/*.md" -o -path "*/adr/*.md" -o -path "*/adrs/*.md" 2>/dev/null | grep -v node_modules | grep -v .git

Step 2: Staleness Checks

ARCHITECTURE.md vs actual structure:

• Read ARCHITECTURE.md and extract mentioned directories/modules
• Compare against actual directory tree
• Flag directories mentioned in ARCHITECTURE.md that no longer exist
• Flag significant directories that exist but are not mentioned

Linked doc resolution:

# Check both AGENTS.md and CLAUDE.md for broken links
for doc in AGENTS.md CLAUDE.md; do
  if [ -f "$doc" ]; then
    grep -oE '\[.*\]\([^)]+\.md\)' "$doc" 2>/dev/null | grep -oE '\([^)]+\)' | tr -d '()' | while read -r ref; do
      if [ ! -f "$ref" ]; then
        echo "BROKEN in $doc: $ref not found"
      fi
    done
  fi
done

ADR recency:

find . -path "*/decisions/*.md" -o -path "*/adr/*.md" 2>/dev/null | grep -v node_modules | xargs ls -lt 2>/dev/null | head -5

Step 3: Coherence Checks

Run the coherence analysis from the codebase-readiness documentation dimension:

# AGENTS.md content type analysis (use AGENTS.md as primary, fall back to CLAUDE.md if it's not a symlink)
DOC="AGENTS.md"
if [ ! -f "$DOC" ] && [ -f "CLAUDE.md" ] && [ ! -L "CLAUDE.md" ]; then
  DOC="CLAUDE.md"
fi

if [ -f "$DOC" ]; then
  echo "Analyzing: $DOC"
  echo "Total lines: $(wc -l < "$DOC")"
  echo "Code block lines: $(sed -n '/^```/,/^```/p' "$DOC" | wc -l)"
  echo "Directive keywords (must/never/always/avoid/prefer): $(grep -ci 'must\|never\|always\|avoid\|prefer' "$DOC")"
  TOTAL=$(wc -l < "$DOC")
  CODE=$(sed -n '/^```/,/^```/p' "$DOC" | wc -l)
  if [ "$TOTAL" -gt 0 ]; then
    PCT=$(( CODE * 100 / TOTAL ))
    echo "Code example percentage: ${PCT}%"
  fi
fi

# Check symlink status
if [ -L CLAUDE.md ]; then
  echo "✓ CLAUDE.md is correctly symlinked to $(readlink CLAUDE.md)"
elif [ -f CLAUDE.md ] && [ -f AGENTS.md ]; then
  echo "⚠ WARNING: Both CLAUDE.md and AGENTS.md exist as separate files. CLAUDE.md should be a symlink to AGENTS.md"
fi

# Topic overlap
DOC="AGENTS.md"
if [ ! -f "$DOC" ] && [ -f "CLAUDE.md" ] && [ ! -L "CLAUDE.md" ]; then
  DOC="CLAUDE.md"
fi

for doc in $(find docs/ doc/ -name "*.md" -maxdepth 2 2>/dev/null | grep -v node_modules); do
  TOPIC=$(basename "$doc" .md | tr '[:upper:]' '[:lower:]' | sed 's/_/ /g')
  if [ -f "$DOC" ] && grep -qi "$TOPIC" "$DOC" 2>/dev/null; then
    DOC_MENTIONS=$(grep -ci "$TOPIC" "$DOC" 2>/dev/null)
    DOC_LINES=$(wc -l < "$doc" 2>/dev/null | tr -d ' ')
    echo "Overlap: '$TOPIC' -- $DOC mentions ${DOC_MENTIONS}x, dedicated doc is ${DOC_LINES} lines"
  fi
done

# Broken references
if [ -f "$DOC" ]; then
  grep -oE '\[.*\]\(\./[^)]+\)' "$DOC" 2>/dev/null | grep -oE '\./[^)]+' | while read -r ref; do
    if [ ! -f "$ref" ]; then
      echo "BROKEN link in $DOC: $ref not found"
    fi
  done
fi

# Source of truth declarations
find AGENTS.md CLAUDE.md docs/ -type f 2>/dev/null | xargs grep -rn "source of truth\|authoritative\|canonical\|definitive" 2>/dev/null | grep -v node_modules | grep -v .git

Step 4: Coverage Checks

• Domain knowledge documentation: Check if docs/DOMAIN.md exists. If it exists, check whether it is populated (has content beyond the template placeholders) or is still a stub. If missing, flag it as a coverage gap with the recommendation: "Create docs/DOMAIN.md to document business domain concepts -- this is the most valuable file for human and AI onboarding."
• Domain directories without nested AGENTS.md: Find major source directories that could benefit from domain-specific AGENTS.md files
• Unlisted directories in ARCHITECTURE.md: Find top-level source directories not mentioned in the codemap
• Missing docs/ categories: Check if guides/, references/, decisions/ exist and have content

Step 5: Report

Present an actionable report:

## Agent-Readiness Audit

### Artifact Inventory
| Artifact | Status | Location | Lines |
|----------|--------|----------|-------|
| AGENTS.md (root) | [Present/Missing] | ./AGENTS.md | [N] |
| CLAUDE.md (symlink) | [Correct symlink/Regular file/Missing] | ./CLAUDE.md | — |
| ARCHITECTURE.md | [Present/Missing] | ./ARCHITECTURE.md | [N] |
| DOMAIN.md | [Present/Stub/Missing] | ./docs/DOMAIN.md | [N] |
| docs/ index | [Present/Missing] | ./docs/README.md | [N] |
| ADRs | [N found] | ./docs/decisions/ | — |
| Nested AGENTS.md | [N found] | [locations] | — |

### Staleness Issues
- [List stale items with specific file paths and what's wrong]

### Coherence Issues
- Primary doc (AGENTS.md or CLAUDE.md) line count: [N] [OK if <150 / WARNING if >150 / CRITICAL if >300]
- Code example %: [N]% [OK if <20% / WARNING if >20%]
- Directive density: [N] directives in [M] lines
- CLAUDE.md symlink status: [Correct/Needs fix]
- Topic overlaps: [list]
- Broken references: [list]
- Cross-document conflicts: [list]

### Coverage Gaps
- Directories without AGENTS.md: [list]
- Directories not in ARCHITECTURE.md: [list]
- Missing docs/ categories: [list]

### Recommended Actions
1. [Highest priority fix -- specific, actionable]
2. [Second priority fix]
3. [Third priority fix]

After presenting the report, offer to auto-fix issues:

• Broken doc links: remove or create the missing file
• Primary doc bloat: offer to run agents-md mode to refactor
• Missing ARCHITECTURE.md entries: offer to run architecture mode to regenerate
• Missing nested AGENTS.md: offer to create starter files for uncovered domains
• CLAUDE.md not a symlink: offer to convert it to a symlink to AGENTS.md