Init

When to use

Use this skill when creating or updating AGENTS.md for a repository.

Use it especially when:

• the current AGENTS.md is long, generic, or stale
• agents repeatedly make the same avoidable mistakes
• repository workflows changed and agent guidance needs pruning

Instructions

Treat AGENTS.md as a living list of non-discoverable landmines and workflow gotchas, not a codebase overview.

Core rule: discoverability filter

Before adding any line, ask:

Can an agent discover this by reading the repo (README, code, config, scripts, directory tree)?

• If yes: do not include it in AGENTS.md.
• If no, and it materially affects task success/cost/safety: include it.

What earns a line

Include only guidance that is:

1. Non-discoverable from repository files alone
2. Operationally significant (changes commands, outcomes, or safety)
3. Actionable (specific enough to execute)

Typical examples:

• Non-standard tooling choices (e.g. use uv instead of pip)
• Command caveats (e.g. tests must run with --no-cache due to fixture behavior)
• Hidden constraints/landmines (deprecated directories still imported in production)
• Critical local conventions that are not encoded in lint/tests/config

What to remove or avoid

Do not include:

• Tech stack summaries
• Directory structure overviews
• Architecture descriptions agents can infer from code
• Generic best-practice advice
• Rules already enforced by tooling (linters, typecheck, tests, CI)
• Mandatory boilerplate headers unless the repo explicitly requires one

Recommended structure

Prefer short, high-signal sections such as:

• Scope & routing (which areas need separate/module-local AGENTS files)
• Non-discoverable commands
• Landmines / do-not-touch areas
• Task-specific constraints

For large repos, recommend hierarchical AGENTS.md files near relevant modules instead of one monolithic root file.

Source files to check first