skill-sunset

Skill Sunset

English | 简体中文

Your AGENTS.md only grows. Which rules are still earning their context?

Skill Sunset is a local, read-only retirement audit for AGENTS.md, CLAUDE.md, and generic SKILL.md instructions. It separates verified breakage and duplicates from unproven “this rule is obsolete” hypotheses. TEST is not RETIRE.

npx skill-sunset@latest audit --codex --open

No global installation is required. No source edits. No AI API. No model quota. No provider credentials.

Third-party integration: HOL Guard v3.0.18 includes a command-safety extension for the installed skill-sunset audit surface. View the merged integration.

If Skill Sunset saves you one risky cleanup pass, star the repository. If a verdict is wrong, share a redacted counterexample.

The screenshot comes from a real report generated by the current CLI from test/fixtures/sample-setup: 5 files scanned, 11 findings, with duplicate retirement, stale-reference updates, progressive disclosure, and behavior hypotheses shown separately. Open the animated walkthrough.

What it does

Skill Sunset combines deterministic checks with conservative review hypotheses:

• finds broken local references, stale absolute paths, malformed Skill frontmatter, oversized always-loaded files, and possible plaintext credentials;
• detects same-name Skills and verifies the complete bundle before recommending recoverable retirement;
• marks model-era compensation rules as TEST instead of claiming they are obsolete;
• produces bilingual HTML, Markdown, JSON, Codex/Claude handoff prompts, an experiment template, and a rollback manifest;
• excludes domain knowledge, safety rules, authorization gates, and project invariants from automatic retirement.

No finding authorizes deletion. TEST means “evaluate this hypothesis,” not “a newer model made this rule unnecessary.”

Four real cases at a glance

On 2026-09-01, the current version scanned two Skill directories actively used by the maintainer. Paths, Skill names, and instruction text were redacted:

Each case has a public, sanitized reproducer: read the full walkthrough or run the fixtures.

Supported environments

Other Linux distributions are expected to work with Node.js 20+, but are not part of the current CI matrix.

Quick start

Scan Codex configuration:

npx skill-sunset@latest audit --codex --open

Scan Claude Code configuration:

npx skill-sunset@latest audit --claude --open

Scan any bounded directory and keep CI-friendly JSON output:

npx skill-sunset@latest audit /path/to/setup --format json --fail-on high

The CLI defaults to --lang auto. Use --lang en or --lang zh-CN to select the primary report language. Every bundle still contains portable English and Simplified Chinese HTML pages.

Complete example: input → finding → validation → rollback

Suppose AGENTS.md contains:

Always use Context7 for every task.
[Deployment runbook](docs/deploy.md)

and docs/deploy.md does not exist.

1. Input and snapshot. Keep a recoverable copy, then audit the directory.

   cp AGENTS.md AGENTS.md.skill-sunset.bak
   npx skill-sunset@latest audit . --out .skill-sunset --open
   

2. Findings. The report can produce:

   • UPDATE / broken-reference: the runbook target cannot be resolved;
   • UPDATE / context7-assumption: current tool availability needs verification;
   • TEST / unconditional-tooling: “for every task” needs representative old-versus-new evaluation.

3. Change and validate. Verify the real runbook path and current tool list first. Change only the confirmed stale reference; make unconditional tooling a separate candidate. Re-run the audit and the project tests:

   npx skill-sunset@latest audit . --out .skill-sunset --format json
   npm test
   

   For a TEST item, fill .skill-sunset/experiment-template.json. Validation runs no commands:

   npx skill-sunset@latest test .skill-sunset/experiment-template.json --root .
   

   Execution requires a separate --run. A passing experiment proves only its encoded acceptance criteria.

4. Rollback. If references, tests, or task behavior regress, restore the saved file and re-run the audit:

   cp AGENTS.md.skill-sunset.bak AGENTS.md
   npx skill-sunset@latest audit . --out .skill-sunset
   

   The generated rollback-manifest.json is intentionally empty until an authorized execution agent records actual changes and hashes.

Report bundle

.skill-sunset/
├── index.html
├── index.en.html
├── index.zh-CN.html
├── audit-report.md
├── audit.json
├── execution-prompt-codex.md
├── execution-prompt-claude.md
├── eval-plan.md
├── activation-checklist.md
├── experiment-template.json
└── rollback-manifest.json

Report contents redact targets below the user home as $HOME/...; other absolute targets are represented as $ABSOLUTE/<name>. The terminal still prints the real local report location so the owner can open it.

activation-checklist.md helps verify whether a runtime actually loads each Skill for two expected paraphrases and rejects one nearby negative case. The core does not read conversation history or call AI. If the runtime exposes no reliable load event, the result stays UNKNOWN; absence of evidence never supports RETIRE.

Verdicts

• MERGE: exact duplicates or conflicting same-name Skills.
• UPDATE: stale paths, references, tools, or version-coupled instructions.
• DEMOTE: useful always-loaded detail that belongs in progressive disclosure.
• RETIRE: byte-identical complete generic Skill bundles with the same name inside one scan root; only recoverable archival is recommended.
• TEST: an obsolescence hypothesis requiring old-versus-new behavioral ev