Agent MD Creator

Produce a durable compass for agents analyzing and working in the repository: where to begin, which project-specific constraints matter, and how to verify relevant work. Keep only guidance that changes a real decision or prevents a demonstrated mistake.

Find the gap

Start with the requested scope, current user decisions, and applicable instruction files. Inspect the README, command definitions, CI, and code only where needed to establish a missing or disputed fact. A focused update does not require a full repository survey.

For an existing file, identify the concrete failure: stale command, missing constraint, conflicting rule, unnecessary reading, repeated approval, or premature stopping. For a new file, identify what an agent would otherwise need to rediscover or could get wrong. Ask only for information that materially changes the instructions and cannot be established locally.

Choose the right home

• Root AGENTS.md: instructions shared across the repository.
• Nested AGENTS.md: commands or constraints that differ for one subtree, when the target host loads nested instructions.
• Existing docs or skills: specialized procedures and explanatory detail. Link with a task trigger, such as "Read docs/schema.md when changing the schema."
• Current task: one-off requests and temporary progress; do not turn them into persistent project policy.

Load references/agents-md-principles.md when resolving instruction scope, migrating files, or preserving decisions and exceptions.