simplify-code/SKILL.md

name, description, license, metadata, allowed-tools

name	description	license	metadata	allowed-tools
simplify-code	Analyze a codebase and produce a single actionable report of simplification & consolidation opportunities — complexity, nesting, duplication, magic numbers, dead code, long functions, duplicated enums/types, near-duplicate functions, reinvented utilities — for an agent to then act on. Detects mechanically with bundled tools (ast-grep, cpd, scc, biome, ruff) and ranks the biggest wins. This skill NEVER modifies code: it only writes a report. Use when asked to simplify, clean up, refactor, reduce complexity, de-duplicate, remove dead code, find reuse, or review anti-patterns in any language (JS/TS, Python, Go, Rust, Java, Svelte/SvelteKit, and more).	MIT	author version simplify-code 0.2.0	Read Write Bash(git:*) Bash(ast-grep:*) Bash(sg:*) Bash(cpd:*) Bash(scc:*) Bash(biome:*) Bash(ruff:*)

Simplify Code

A report generator, not an editor. It analyzes a codebase and writes one actionable report; it never modifies source files. The calling agent reads the report and decides what to act on. Runs the same way in any runtime (Claude Code, GitHub Copilot CLI/VS Code, pi, Codex, Gemini CLI).

It keeps the codebase out of your context: bundled binaries find and rank candidates mechanically; you assemble a small JSON ledger on disk; the model is used only to judge cross-file candidates, never to edit.

"run" = execute via your shell/terminal tool; "read the span" = read only the indicated line range. There is no edit step — this skill does not change code.

When to use

When the user wants to simplify / clean up / refactor / de-duplicate / reduce complexity / remove dead code / find reuse / review anti-patterns — for a file, directory, or repo. The output is a report the user (or the agent) then acts on separately.

What it produces (the output contract)

Always exactly two files under simplify/ in the target repo — nothing else is written:

1. simplify/findings.json — the machine-actionable ledger. Every finding MUST carry: id, kind (structural|lint|metric|consolidation), detector, title, members ([{file,line}]), severity (0–100), confidence (0–1), action (a concrete, executable instruction — what to change), verify (the command(s) to confirm it after acting), status (pending initially), and for consolidation: verdict (consolidate|partial|keep-separate). Schema + example: assets/ledger.schema.json.
2. simplify/<report>.md — a ranked, human/agent-readable action queue built from the ledger, plus a "kept separate (and why)" section.

Every reported finding is independently executable: an agent can take one finding, do its action, run its verify, and mark status: applied — without re-running this skill.

How it works (overview)

locate engines → scope files → DETECT (Pass A structural + Pass B consolidation/lint/metrics)
   → infer build/test (for the `verify` fields) → assemble findings.json (each with action+verify)
   → JUDGE cross-file candidates (cheap model + AHA guardrails) → write report. No edits, ever.

No modes, no flags, no apply step. The skill analyzes and reports; acting is the agent's job.

---

Step 0 — Locate the engines

Bundled per platform (bin/manifest.json) — no install. Detect <os>-<arch>:

• OS: Linux→linux, macOS→darwin, Windows→win32. Arch: x86_64→x64, arm64→arm64.

Required: ast-grep at <skill-dir>/bin/<os>-<arch>/ast-grep (.exe on Windows; chmod +x on Unix). Aux (for Pass B): cpd, scc, biome, ruff in the same dir. Verify ast-grep --version. Binaries are git-lfs; if a file is an LFS pointer/missing, run git lfs pull, else fetch the asset from bin/manifest.json and verify against bin/checksums.txt, else use a PATH copy, else degrade (that detector is skipped with a note). Absence of any aux tool never blocks the run. Refer to the main binary as AST_GREP.

Step 1 — Scope

Read-only scoping; never touch git-ignored files.

• Git repo: candidates = git ls-files + git ls-files --others --exclude-standard.
• Not a git repo: ask which paths to include.
• Honor any path the user named (intersect with the above).
• Test files are excluded (their literals/structure are usually intentional). Filter:

  \.(test|spec)\.[mc]?[jt]sx?$ · (^|/)(__tests__|tests?|e2e|__mocks__|__snapshots__)/
  _test\.go$ · (^|/)test_[^/]*\.py$|_test\.py$|conftest\.py · (^|/)src/test/|Tests?\.java$
  

  Record config.include_tests: false. (Widen only if the user explicitly asks to include tests.)

Step 2 — Detect (mechanical, ~0 model tokens)

Pass A — structural (AST_GREP scan -c <skill-dir>/sgconfig.yml --json=compact <paths>): redundant booleans, magic numbers, deep nesting, long params, etc. (references/DETECTION.md). For Svelte .svelte, see references/SVELTE.md (project tooling / opt-in grammar).

Pass B — consolidation & anti-patterns (references/CONSOLIDATION.md for the full method):

• Duplicate enums/labels/unions — AST_GREP extracts enum/union/as const defs → member-set cluster.
• Near-duplicate functions — cpd <paths> --min-tokens 50 --reporters json --output simplify/cpd --silent (exact) + AST_GREP skeleton extraction (renamed/structural).
• Untyped repeated DTOs — AST_GREP extracts object literals → key-set cluster; keep only shapes repeated ≥3× with no matching interface.
• Reinventing-the-wheel — AST_GREP function-signature index → name/signature similarity.
• Lint (defer, don't reimplement) — bundled biome lint --reporter=json <paths> (JS/TS) and ruff check --output-format=json <paths> (Python), read-only. Deeper/type-aware/other-language → optional project toolchain only-if-present.
• Metrics — scc --by-file -f csv --no-cocomo <paths> (+ ast-grep-derived nesting/length/params) → flag god/long functions.
• Frontend component extraction (F5) — references/COMPONENTS.md. F5a: ast-grep extracts JSX/template elements (kind: jsx_element; Vue/Svelte/Angular via the opt-in grammars in sgconfig.frontend.yml) → skeleton-cluster repeated markup (cpd alone misses renamed markup) → judge → "extract <Name> (dumb/smart) used in N places, props {…}". F5b: flag god components (large render + many state/effect hooks) → judge a smart-container/dumb-child split. Classify dumb vs smart by counting state/effect/ store/fetch signals (per-framework table in COMPONENTS.md). Trigger words: component, reuse, duplicated UI/markup, presentational/container, dumb/smart, extract component.

Step 3 — Infer build / test / lint (for the report's verify fields)

Infer from manifests (don't hardcode) and record in config; these are written into each finding's verify so the agent can confirm its own changes later. NOT run by this skill.

• Node package.json scripts; Python pytest/ruff; Go go build/test; Rust cargo build/test; Java Maven/Gradle. Set null if absent.

Step 4 — Assemble findings + judge cross-file candidates

Write simplify/findings.json (use a cheap/fast model). For each candidate produce a finding with the full output contract (id, kind, detector, title, members, severity, confidence, action, verify, status:pending; verdict for consolidation).

• Structural / lint / metric findings: action = the concrete fix (for a mechanical ast-grep rule, the suggested rewrite or AST_GREP scan --rule <id> --update-all; for a semantic one, the pattern from references/PATTERNS.md + the span). verify = config build/test (+lint).
• Consolidation (Pass B) findings are mandatory-judged before inclusion: give the cheap model the real spans and apply the judge contract + AHA guardrails in references/CONSOLIDATION.md. Only include verdict != keep-separate with confidence ≥ 0.6. Record rejected clusters under kept_separate (with the reason) so reruns don't re-flag. Fan out one judge per cluster where the runtime supports sub-agents.

Rank by severity (biggest win first). Resumable: if findings.json exists, keep entries already status: applied and refresh the rest.

Step 5 — Write the report

Write simplify/consolidation-report.md: a header (mode, scope, config commands), a ranked action queue (one block per finding: id · verdict/kind · confidence · title · Where · Do (the action) · Verify · Why), a "Kept separate (do NOT consolidate)" section, a latent drift/bugs callout, and short Pass-A/lint/metric summaries. See the example in assets/ledger.schema.json and references/CONSOLIDATION.md.

Then stop. The skill's job is done; the agent acts on findings.json / the report.

---

Guardrails

• This skill never modifies source files — no edits, no autofix, no formatting. It only writes simplify/findings.json and simplify/*.md.
• Never read or report on git-ignored files. Test files excluded by default.
• Pass B is judge-gated: report only real, confident findings; preserve intentional duplication (AHA — rule of three, don't merge across layers/bounded contexts).
• Keep your own context lean: work from tool output + the ledger, not whole files.
• If not a git repo, ask for scope before analyzing.

References

• Detection rules & enrichment: references/DETECTION.md · Pattern catalog: references/PATTERNS.md
• Consolidation pipeline + judge contract + AHA guardrails: references/CONSOLIDATION.md
• Frontend component extraction (dumb/smart): references/COMPONENTS.md
• AI anti-pattern taxonomy → treatment: references/ANTIPATTERNS.md
• Token/model tactics: references/OPTIMIZATION.md · Per-runtime notes: references/PORTABILITY.md
• Svelte / SvelteKit: references/SVELTE.md · Bundled engines: bin/manifest.json