How to Audit AGENTS.md and CLAUDE.md for Stale Instructions — Without Deleting Anything

Description and use

Skill Sunset audits AGENTS.md and CLAUDE.md for stale, duplicate, or conflicting rules, producing a safe, evidence‑based cleanup plan with test templates.

Problem

AI coding agents’ instruction files grow over time, leading to stale, duplicate, or conflicting rules that are hard to clean up safely.

Outcome

The audit identifies 11 findings across 5 files, including 2 UPDATE, 1 DEMOTE, 1 RETIRE candidate, and 7 TEST hypotheses, enabling safe, evidence‑based cleanup.

Workflow

• Run npx skill-sunset@latest audit --codex --open or --claude for a local audit
• Review the generated advisory report bundle
• For TEST findings, generate an experiment template with npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .
• Run experiments only with --run and optionally --inherit-env
• Validate results, obtain human approval, then archive or edit the instruction
• Re‑audit to confirm changes
• Integrate with HOL Guard if desired

Evidence

The audit is local and read‑only. The core does not call an AI API, consume model quota, or read provider credentials.

Source

The deterministic findings include a broken local Markdown reference and a complete duplicate generic Skill bundle.

Source

For a TEST finding, Skill Sunset generates an experiment template.

Source