Agent Instructions Doctor

The problem

Instruction files like CLAUDE.md or .cursorrules decay into "token scar tissue" over time. Agents start ignoring rules, behaving inconsistently, or hallucinating based on stale conventions for retired frameworks.

What it does

• Identifies direct and partial contradictions across multiple instruction files like AGENTS.md and .cursorrules.
• Cross-checks rules against the actual repository to find dead paths, missing scripts, and retired framework references.
• Flags "token bloat" and unenforceable rules that consume context without changing agent behavior.
• Audits instruction placement to ensure high-priority rules are positioned where the LLM is most likely to attend to them.
• Generates a prioritized report of harmful, inert, and missing instructions with ready-to-paste diffs.

Frameworks & tools

Works with Cursor (.cursorrules), Claude Dev/Roo Code (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), and generic project AGENTS.md files.

Why this beats prompting it yourself

Manually auditing 2,000 tokens of rules for logical consistency is error-prone. This skill performs a multi-pass analysis that specifically checks for "hidden overrides" in nested directories that a standard prompt would likely miss.

Use cases

• Fixing an agent that keeps using the wrong library version despite instructions.
• Reducing token costs in large monorepos with bloated context files.
• Onboarding a new agent to a legacy project with outdated documentation.
• Consolidating fragmented rules from three different editor-specific config files.

Known limitations

Does not access external networks. It analyzes and edits instruction files only, not the underlying application logic.