Create a code-scans skill

A code-scans skill turns a vague "find things to simplify" request into a few well-proven candidates instead of a pile of guesses, and keeps a surveying agent from proposing to delete the product. Generic advice cannot do that; what makes the survey safe and useful is repo judgment: which surfaces are intentional even when nothing calls them, what counts as a production consumer here, where the trust boundary sits, which gate already catches the easy cases, and where a finding is supposed to go. This skill extracts that judgment from the repo and writes it into .agents/skills/code-scans-<project>/SKILL.md, with .claude/skills/code-scans-<project> as a symlink to the same directory for Claude Code. Write it for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the repo.

1. Interview the repo, not the user

Answer these from the checkout and only ask the user what you cannot observe:

• Doctrine. Read AGENTS.md, CLAUDE.md, CONTRIBUTING.md, REVIEW.md, SECURITY.md, and docs/ for anything that names a failure mode (over-engineering, scope discipline), a testing doctrine (are tests golden truth or not?), a dependency policy (zero runtime dependencies, or dependencies-over-hand-rolling?), a prose standard, or a documented contract with published numbers. Each of these changes what a "strong candidate" means.
• Layout and corpora. Walk the tree and decide what is production, non-production, and ambiguous. Production is what ships or runs: source roots, entry points, manifests, build-time scripts, tracked skills. Non-production is tests, docs, comments, snapshots, generated expected outputs. Ambiguous is anything that might be a product smoke path or an integration contract (examples, evals, e2e suites). Note reachability rules (a symbol only an entry file exports is still production if that entry is published), generated directories to ignore, and that anything git ls-files does not list is out of scope.
• Protected surfaces. Find what is intentional even when it looks unused: documented decisions (a notes tree, ADRs, residual-risk registries), contract corpora and snapshot surfaces that are byte contracts, published limits, per-integration directories that each exist for a real external host, deliberate twins or seams, and public exports where repository-local absence cannot prove no external consumer. Cite where the repo says each one is intentional; do not invent protected seams.
• Trust boundary. Name which inputs are untrusted (wire payloads, user config, fetched rulebooks, model output, durable files, worker or process boundaries) and which are same-process handoffs that ordinarily borrow values. This decides whether a defensive copy, freeze, or re-validation is contract or bloat.
• Tooling. Find the existing gates and their caveats: dead-code and duplication tools (knip, jscpd, ts-prune, vulture, cargo udeps, and similar), the one check command the repo wants run, lint, and pre-push hooks. Record what the tools cannot see (dynamic string dispatch, @internal tags that mean test-only-by-design, production-only modes) so the survey does not stop where the tool stops.
• Deliverable channel. Decide where findings go. A repo with a notes or ADR system that has lifecycle and placement rules wants proposals written there in its format; a repo with a solo maintainer and no notes system wants a report and no new structure. Record inline TODO conventions and urgency semantics, PR conventions, and the base branch name.
• Validation. Record which commands prove a docs-only change versus an implemented removal, and which pieces must never be run separately.
• Recent history. Skim git log for cutovers, retired directories, removed dependencies, and renamed terminology. The skill must describe the current tree, not the one that existed when the docs were written.

Ask the user only for the unobservable: seams that are off-limits beyond what the docs say, and whether the surveying agent may implement removals when the docs are silent.