SKILL.md

name: initialising-and-updating-agents-md description: Analyses a codebase and creates or updates AGENTS.md to help future agents work effectively. Use when asked to initialise, generate, or update an AGENTS.md file, or when the user says "init agents", "generate agents.md", or wants to document a project for agent use. license: GPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Analyse the codebase and produce an AGENTS.md that documents what an agent cannot discover on its own by reading the code.

Research from ETH Zurich shows that auto-generated AGENTS.md files reduce task success by ~3% and inflate costs by 20%+ because they duplicate what agents already find by reading the repo. Human-written files help only when they contain non-discoverable information. The key filter for every line: can an agent figure this out by reading the code? If yes, don't write it.

Precondition

Check whether the directory is empty or contains only config files (e.g. .gitignore, .editorconfig, lock files). If so, stop and tell the user:

Directory appears empty or only contains config. Add source code first, then run this command to generate AGENTS.md.

Discovery

  1. Directory contents: Run ls to get the lay of the land
  2. Existing rule files: Check for and read any that exist:
    • .cursor/rules/*.md, .cursorrules
    • .github/copilot-instructions.md
    • claude.md, CLAUDE.md
    • agents.md, AGENTS.md
  3. Project type: Identify from config files and directory structure (e.g. package.json, Cargo.toml, go.mod, pyproject.toml, Makefile)
  4. Commands: Find build/test/lint/run commands from config files, scripts, Makefiles, CI configs — especially single-file and single-test variants
  5. Source patterns: Read representative source files to identify non-obvious conventions
  6. Existing AGENTS.md: If one exists, read it — you're improving, not starting from scratch

What belongs in AGENTS.md

Agents can grep the entire codebase before you finish typing your prompt. They don't need a map — they need to know where the landmines are.

Include (non-discoverable):

  • Commands that differ from convention — uv instead of pip, bun instead of npm, custom test runners, single-file lint/typecheck variants
  • Gotchas that break silently — "run tests with --no-cache or fixtures give false positives"
  • Non-obvious constraints — "the legacy/ directory is deprecated but three production modules import from it; don't delete anything in it"
  • Tooling the agent should prefer — custom scripts, linters, formatters that aren't obvious from config
  • Project-specific guidance from existing rule files discovered during step 2

Omit (discoverable):

  • Codebase overviews and directory listings — the agent reads these itself
  • Tech stack and framework descriptions — visible in config files
  • Code style details — agents are in-context learners; they'll match existing patterns. Use linters and formatters instead.
  • Architecture explanations — agents infer this from the code
  • Anything the agent would find by reading the README, config files, or source

Progressive disclosure

For monorepos or large projects, don't stuff everything into one root file. Place focused AGENTS.md files at the relevant directory level:

AGENTS.md              # repo-wide: tooling, gotchas, commands
services/api/AGENTS.md # API-specific: custom middleware pattern, DB migration gotchas
packages/ui/AGENTS.md  # UI-specific: design token locations, component patterns

Agents read the nearest file in the directory tree, so the closest one takes precedence.

Output principles

  • Short. Every line goes into every agent session. Aim for under 60 lines; under 30 is better. Each line must justify its token cost.
  • Landmines, not maps. Document what will trip the agent up, not what it can see for itself.
  • Commands first. Put executable commands early — agents reference them often. Prefer single-file variants (npm run tsc --noEmit path/to/file.tsx) over project-wide builds.
  • Living document. Treat it like a bug tracker, not a wiki. When the agent trips on something non-obvious, add a line. When you fix the root cause, delete the line.
  • Only document what you observe. Never invent commands, patterns, or conventions.
  • Preserve existing content when updating. Merge new findings; don't discard prior work without reason.