improve-agent-instructionslisted

<!-- Generated from https://github.com/nielsmadan/agentic-coding — edits here are overwritten. --> # Instruction-File Improver Audit, evaluate, and improve the instruction files that load into **every** agent session — `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and their package-level equivalents. Can also capture session learnings into them. **The governing idea:** this file is a permanent, per-session token cost paid by every agent that reads it. Keep it lightweight, spend most of its budget on **gotchas**, and push depth behind pointers (skills, `docs/`) that load only when relevant. Restating what the agent can see for itself — the directory tree, the dependency list, the catalog of available skills — costs tokens in every session and buys nothing. ## Gotchas - In this repo, `~/.claude/` is symlinked — changes to the global instruction file here affect all projects. Warn about cross-project impact before proposing changes to a committed, shared file. - The cross-referencing step is easy to do superficially, producing a high score that misses stale paths. Actually resolve the references. - **Multi-harness repos:** `AGENTS.md` is read by Codex, Pi and OpenCode; `CLAUDE.md` by Claude Code. Advice that leans on one tool's specific mechanisms doesn't belong in the shared file. Prefer `AGENTS.md` as canonical with `CLAUDE.md` a one-line `@AGENTS.md` bridge. ## Instructions ### Step 1: Discovery Find all instruction files: ```bash find . \( -name "AGENTS.md" -o -name "CLAUDE