AGENTS.md Scaffold

Use this skill to generate a small, evidence-backed AGENTS.md stack for a repository. The output may be a plan, exact proposed file contents, or applied files when the user explicitly asks to write them.

This skill is for instruction scaffolding. Use repo-agent-context-audit first when the user only asks whether the repo's agent context is healthy.

Operating Contract

Default to a scoped plan before editing. Only write or modify AGENTS.md, CLAUDE.md, WARP.md, hooks, settings, or generated docs when the user has explicitly asked to apply the scaffold.

Direct actions:

• Run read-only discovery, scanner commands, and repo command inspection.
• Produce a scoped AGENTS.md plan with evidence and validation commands.
• Draft exact file contents when the user asks for proposed text.

Escalate before:

• Creating or editing high-context files when the user only asked for an audit.
• Rewriting existing AGENTS.md, CLAUDE.md, or WARP.md instead of adding a short pointer or scoped complement.
• Batch-normalizing multiple repositories.

Evidence-backed pushback:

• Challenge new scoped files when the directory has no distinct local rules.
• Challenge guessed commands, ownership, or generated-file rules unless repo evidence supports them.

Feedback loop:

• Promote repeated false starts into references/scaffold-agents.md, scanner signals, or eval prompts.

Workflow

1. Discover Existing Context

Run the scanner from this skill directory when possible:

python3 scripts/scan_repo_context.py <repo-root>
python3 scripts/scan_repo_context.py <repo-root> --json

Then inspect the files that matter:

• existing AGENTS.md, CLAUDE.md, WARP.md, .claude/instructions.md, and .github/copilot-instructions.md
• README.md, CONTRIBUTING.md, package manifests, Makefiles, CI workflows, and documented test commands
• generated files and their generators
• high-risk directories such as migrations, deploy scripts, auth, secrets, payments, registry metadata, generated clients, and production operations

Do not infer commands or ownership from names alone. Use scanner output as a lead, then verify with actual files.

2. Choose The Instruction Stack

Read references/scaffold-agents.md before proposing files. Choose the smallest stack that changes agent behavior:

• root AGENTS.md for repo-wide routing and validation
• nested AGENTS.md only where directory rules differ from root
• no nested file for directories that only need ordinary README context
• no bulk normalization across multiple repos until a few examples have been manually validated

3. Produce A Candidate Plan

Before editing, report:

## Scoped AGENTS Plan

| Path | Why here | Rules to include | Validation |
|---|---|---|---|
| `AGENTS.md` | <repo evidence> | <root topics> | `<command>` |
| `<dir>/AGENTS.md` | <repo evidence> | <scoped topics> | `<command>` |

## Files To Preserve

- `<existing high-context file>` - <how it will be referenced or left alone>

## Open Facts

- <missing command or ownership fact that cannot be inferred>

4. Scaffold On Request

When applying the scaffold:

• keep root files short, normally 80-150 lines
• keep nested files focused on that directory's ownership, source-of-truth rules, and validation commands
• include real commands and paths, not placeholders, unless the fact is truly missing
• preserve existing high-context files unless the user requested a rewrite
• pair every prohibition with a concrete alternative, helper, generator, or command

Decision Gates

Situation	Action
Existing CLAUDE.md or WARP.md is already a good router	Add a short AGENTS.md pointer only if cross-runtime routing helps.
Root instruction file exceeds roughly 200 lines	Propose root router plus scoped files or references.
Directory has generated outputs	Add scoped rules naming source of truth and regenerate/check commands.
Directory has distinct safety rules	Add scoped rules with escalation boundaries.
Directory has ordinary implementation files only	Keep guidance in root unless conventions differ.
Commands cannot be verified from repo evidence	Leave an open fact instead of guessing.

Gotchas

• Do not add nested AGENTS.md files for every directory. Add them only where local rules differ from root.
• Do not guess build, test, lint, or generator commands from framework names. Cite the manifest, CI workflow, script, or docs that prove the command.
• Do not overwrite an existing CLAUDE.md, WARP.md, or AGENTS.md just to normalize naming. Preserve it, point to it, or propose a split first.
• Do not put long architecture explanations in root AGENTS.md; route to references or existing docs instead.

Verification

After applying changes:

• run the repo's narrow validation command for the affected scope
• run any repo-wide registry, docs, typecheck, lint, or test command named in the new instructions when practical
• rerun python3 scripts/scan_repo_context.py <repo-root> if using the bundled scanner to confirm scoped files are discoverable

If verification cannot run, report the exact missing precondition and the command that should be run later.

Resources

• scripts/scan_repo_context.py: read-only scanner for high-context files, command hints, specs, local skills, and scoped AGENTS.md candidates.
• references/scaffold-agents.md: scaffold selection rules and templates for root, generated metadata, scripts/tools, skill libraries, and tests.
• evals/evals.json: lightweight prompts for future behavior checks.