askit-build-agents-md
Purpose
Author and keep current a plugin's AGENTS.md: the project-level agent instructions and navigation entrypoint, the first thing an agent reads (Standard sec 3.10). It is the single most portable cross-tool surface (Claude, Codex, Gemini, Copilot, and Cursor all read AGENTS.md). Two modes: create authors a tight AGENTS.md; improve syncs it to the component index and trims it. Authoring depth is in references/authoring-agents-md.md. Follows the shared builder contract (../../docs/reference/builder-pattern.md).
When to use
When the user asks to author, write, sync, or trim AGENTS.md (or CLAUDE.md), or when components were added or removed and the navigation is stale.
create mode
- Brief interview: what the project is, the conventions (runtime, build/test/lint), and the boundaries. Skip if in context.
- Author a TIGHT AGENTS.md: what-this-is, current-state (read before assuming capabilities), conventions, build/test/lint, where-to-look. Keep it minimal and essential-only, and prefer positive instructions over long "do not" lists. Verbose, generated-looking context files measurably reduce agent task success and raise cost, so brevity is a feature, not a shortcut.
- Keep the component list aligned with
library.jsonand the index.node scripts/generators/sync-agents-md.mjsrenders the component section from the manifest so it does not drift. - Evaluate (
node scripts/evaluate.mjs . --json); AGENTS.md presence is checked by U2 (anatomy), and the description and instruction-budget rules apply.
improve mode
- Run evaluate and read findings; sync the component list to disk.
- Trim: remove redundancy and non-essential prohibitions; judge each change by whether it helps an agent act correctly, not by length.
- Re-run to confirm.
Scope
AGENTS.md is Universal-tier and the cheapest credible cross-tool surface. Keep it brief and current; the generated component section (sync-agents-md) prevents drift from the manifest. A CLAUDE.md is a Claude-specific sibling for the same purpose when a project needs Claude-only guidance.