improve-agents-md

Progressively improve (or bootstrap from scratch) a project's agent-instruction file. Works on both AGENTS.md (vendor-neutral convention from OpenAI Codex, also read by Cursor, Claude Code, and others) and CLAUDE.md (Claude-specific). Keeps one canonical file on disk and symlinks the other, so every agent reads the same source of truth.

When to Use

• User invokes /improve-agents-md (or /improve-claude-md pointed here)
• User asks you to "clean up", "shorten", "audit", or "rewrite" their CLAUDE.md / AGENTS.md
• User complains that Claude (or another agent) keeps ignoring their project rules
• User is about to onboard a new agent and wants to check their instructions are any good
• No AGENTS.md / CLAUDE.md exists and the user wants to set one up properly

The Core Problem

Claude Code (and most other agents) inject the project agent-file with a system reminder that says:

"this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."

So the agent will ignore parts it deems irrelevant. The more content that isn't applicable to the current task, the more likely the agent is to ignore the entire file — including the parts that matter right now. Long, undifferentiated agent files are self-defeating.