/repo-agent-context-audit

name: repo-agent-context-audit
description: Audit and recommend improvements for a repository's agent-readable context, including AGENTS.md, CLAUDE.md, WARP.md, CONTRIBUTING.md, .agents/skills, and specs/ PRODUCT.md and TECH.md contracts. Use when asked to review, score, assess, or standardize repo instructions, agent onboarding, spec workflows, or cross-repo agent-context conventions. Use agentsmd-scaffold instead when the user wants to generate or apply root/scoped AGENTS.md files.

Repo Agent Context Audit

Overview

Assess whether a repository has a small, usable agent context stack: a short top-level instruction file, task-specific skills, and behavior/implementation specs for substantial work. Default to a read-only audit and minimal recommendations; create or edit high-context files only when the user explicitly asks.

If the user asks to generate, split, or apply root/scoped `AGENTS.md` files, handoff to `agentsmd-scaffold`. This skill may identify that scaffold as the smallest useful change, but should not duplicate the generation workflow.

Default Standard

Prefer this three-layer shape:

1. `AGENTS.md` or repo-equivalent: 80-150 lines, top-level routing only. 2. `.agents/skills/<task>/SKILL.md`: reusable workflows for common fragile tasks. 3. `specs/<id>/PRODUCT.md` and `specs/<id>/TECH.md`: checked-in contracts for substantial features.

Do not force this exact layout when a repo already has a coherent equivalent, such as `WARP.md`, `CLAUDE.md`, `CONTRIBUTING.md`, or framework-specific instruction files. Map existing files to the layers first, then fill only the real gaps.

Workflow

1. Discover

Run the read-only scanner when possible:

# From this skill directory:
python3 scripts/scan_repo_context.py <repo-root>

Then inspect the important files directly. Always search before creating:

• `AGENTS.md`, `CLAUDE.md`, `WARP.md`, `.claude/instructions.md`
• `CONTRIBUTING.md`, `README.md`, `.github/copilot-instructions.md`
• `.agents/skills/*/SKILL.md`
• `specs/**/{PRODUCT,product,TECH,tech}.md`

If multiple instruction files overlap, record their scopes and precedence instead of merging them by default.

2. Classify

Classify the repo into one of these states:

• **Healthy**: short top-level guidance, task workflows, and specs are discoverable.
• **Missing top-level router**: useful docs exist but agents lack an entrypoint.
• **Overloaded top-level file**: one file mixes rules, workflows, architecture, and reference data.
• **Specless complex repo**: substantial work happens without PRODUCT/TECH contracts.
• **Stale or divergent**: instructions contradict code, scripts, or observed repo conventions.
• **Unsafe to modify**: high-context files are generated, externally owned, or conflict across scopes.

3. Score

Use the rubric in `references/standards.md` for:

• top-level routing quality
• progressive disclosure
• procedural workflows
• decision gates
• production examples
• spec quality
• validation mapping
• stale or conflicting guidance risk

4. Recommend

Lead with the smallest useful change. Good recommendations usually look like:

• Add a short `AGENTS.md` that points to existing docs instead of duplicating them.
• Split a long top-level file into a router plus references or skills.
• Add `.agents/skills/write-product-spec` and `.agents/skills/write-tech-spec` only if spec writing is repeated.
• Add `specs/<id>/PRODUCT.md` and `TECH.md` templates only if the repo ships substantial features.
• Remove or rewrite stale instructions only after citing the conflict.

5. Handoff Or Scaffold Only On Request

When the user explicitly asks to generate, split, or apply root/scoped `AGENTS.md` files, use `agentsmd-scaffold` instead of duplicating that workflow.

When the user asks for exact PRODUCT/TECH spec templates or non-AGENTS context scaffolding, read `references/templates.md` and adapt the templates to the repo. Before editing:

• identify every `AGENTS.md` or equivalent whose scope covers the target path
• preserve existing high-context files unless the user asked for a rewrite
• keep generated docs small
• include actual repo commands, paths, and test gates
• leave placeholders only when the repo truly lacks the fact

Decision Gates

| Case | Action | |---|---| | Small bugfix repo with README and clear tests | No spec system; maybe add a short `AGENTS.md` router | | Repeated feature work with review churn | Add PRODUCT/TECH spec workflow | | User asks to generate or apply root/scoped `AGENTS.md` files | Use `agentsmd-scaffold` | | Existing `CLAUDE.md` or `WARP.md` is good | Link it from `AGENTS.md` or leave it as the repo-equivalent | | Multiple teams or nested packages | Use scoped nested `AGENTS.md` only where rules genuinely differ | | High-context file over 200 lines | Split into top-level router plus referenced skills/docs | | User asks for bulk normalization | Audit first; do not batch edit until 2-3 repos have been manually validated |

Operating Contract

Direct actions:

• Run read-only discovery, scoring, and scanner commands.
• Produce an audit report with cited files and smallest useful changes.
• Draft exact non-AGENTS scaffold content when the user asks for proposed text.
• Handoff AGENTS.md generation or application to `agentsmd-scaffold`.

Escalate before:

• Creating or editing `AGENTS.md`, `CLAUDE.md`, `WARP.md`, hooks, settings, or generated docs.
• Rewriting existing repo instructions instead of adding a short router or pointer.
• Batch-normalizing multiple repositories.

Evidence-backed pushback:

• Challenge new skill/spec scaffolding when the repo is small, has no repeated workflow, or already has a coherent equivalent.
• Challenge edits when the only evidence is style preference rather than a real agent failure, review bottleneck, or missing workflow.

Feedback loop:

• Promote repeated audit findings into the target repo's router, a task skill, or a spec template.
• Keep this skill's rubric and tem