back
loading skill details...
Grade how vibe-coded a codebase is. Produces a Slop Percentage (0-100% AI slop), a tier ranking from Senior Engineer down to "GPT-3.5, Unsupervised", and an...
---
name: slop-check
description: Grade how vibe-coded a codebase is. Produces a Slop Percentage (0-100% AI slop), a tier ranking from Senior Engineer down to "GPT-3.5, Unsupervised", and an HTML report card served at a local URL with specific file:line findings and copy-paste fix-it prompts. Use whenever the user wants to slop-check or grade a repo, asks how vibe-coded / AI-generated / sloppy / well-architected a codebase is, wants a code quality score, roast, audit, or report card, or mentions AI slop, vibe coding, or code smells — even if they don't name the skill.
---
# slop-check
Grade a codebase's slop level. Fun on the surface, real code review underneath: every point
of slop must cite a real file and line. The roast is the headline; the receipts are the product.
This skill is agent-agnostic — nothing in it depends on a specific coding agent. The only
requirement is Node 18+ on the machine.
## Process
### 1. Resolve the target
The target repo is the argument if given, otherwise the current working directory.
If the target has fewer than 5 code files, tell the user there isn't enough to grade and stop.
**Always double-quote every path in the shell commands below.** Project paths often contain
spaces (e.g. `~/Documents/My Project/`), and an unquoted path silently writes the report to
the wrong place. Write `"$ROOT/.slop-check/metrics.json"`, never
`$ROOT/.slop-check/metrics.json`. The scripts themselves handle spaces fine; the only risk
is an unquoted path in the command you run.
If a file you just wrote then "isn't there," do NOT conclude that a watcher, dev server, or
cleanup hook is deleting it, and do not alarm the user with that theory — this skill never
deletes anything, and that misdiagnosis has happened before. The real cause is almost always
an unquoted path that wrote the file somewhere other than where you looked. Re-run the
command with the path fully quoted and `ls` the exact quoted path before assuming anything
external is at fault.
### 2. Run the deterministic scanner
```bash
node <this-skill's-directory>/scripts/slop-scan.mjs <target-root> --out <target-root>/.slop-check/metrics.json
```
This is dependency-free (Node 18+, no installs). It produces `metrics.json` containing:
- File inventory, language breakdown, line counts
- Import graph metrics: circular dependencies, god files, possibly-dead orphan files
- Cross-file duplication estimate (hashed line windows)
- AI-tell counts from regex (narrating comments, "in a real app", placeholder TODOs, leftover debug logging, commented-out code)
- Utils-folder sprawl, giant files
- **Pre-computed subscores** for the four script-owned categories (Coupling, Duplication, Dead Weight, AI Tells)
- `sampleSuggestions`: the files most worth reading by hand in step 3
The scanner also writes `.slop-check/slop-map.json` — the full per-file import graph
(every file's `importedBy` / `imports` lists plus flags). Do NOT read it whole (it can be
large); it exists so step 5's fix-it prompts and any future fixing agent can pull exact
context without re-exploring the repo. Pull individual entries from it when you need a
specific file's blast radius.
Read the whole `metrics.json` before continuing. Treat orphan files as *suspects*, not
convictions — dynamic loading, workers, and cross-package imports can hide real users.
If `truncated` is true (the repo exceeded the 50,000-code-file walk cap), say so in the
verdict — never let a partial scan read as full coverage.
Each run is self-contained — a fresh snapshot of the code as it is right now. If a
previous run left anything in `.slop-check/` (or an old `slop-report.html`), ignore its
contents entirely and overwrite it. Do not read old reports, compare against them, or
carry findings forward; code changes too much between runs for that to mean anything.
The grade reflects the current state, nothing else.
### 3. The taste pass (judgment)
The files in `sampleSuggestions` (plus any the metrics make you suspicious about) get
judged against `references/HEURISTICS.md` — read it now if you haven't. The categories
being scored here:
- **Architecture & Modularity** — deletion test, shallow modules, pass-through layers, horizontal slicing, layering violations
- **Naming & Domain Language** — generic names, no consistent domain vocabulary
- **Consistency** — mixed paradigms, styles, and conventions that show nobody was steering
Scale the effort to the repo — a slop-check takes minutes, not hours:
- **Small repo (under ~40 code files):** read the sample yourself. No subagents.
- **Bigger repo, and your environment supports parallel subagents:** spawn reviewers in
**one parallel batch — at most 6, with no second wave.** There are three lenses; start
with one reviewer per lens, and when a lens's file list exceeds ~40 files, split that
list across two reviewers with the same lens (this is how you reach 4-6 — more files
per reviewer just means skimming, which is worse than sampling):
1. *Architecture* — the god files, largest files, and most-imported files; hunts
shallow modules, pass-through layers, layering violations.
2. *Naming & consistency* — the spread sample (files from different corners of the
repo); hunts generic naming, vocabulary drift, mixed conventions.
3. *AI tells & local quality* — the highest-tell files; confirms or refutes the
regex counts and hunts the tells regexes can't catch.
Tell each reviewer to read `references/HEURISTICS.md`, read only its assigned files,
and return JSON with two things: `findings` (`{category, file, line, severity,
description}` with the severity scale below) and `observations` — one line per file
read (`{file, observation}`) capturing what the file *is* and how it relates to its
neighbors, even when there's nothing wrong with it. The observations are not for
scoring; they're the knowledge that makes step 5's fix-it prompts context-rich, so the
tokens spent reading don't evaporate. Then merge everything yourself, dedupe anything
two reviewers both caught, and own the final category scores — reviewers report,
you grade.
- **No subagent support:** do the three lenses yourself, sequentially, over the same sample.
If you ever feel the urge to spawn a seventh agent or a second wave, stop — you are
rebuilding the hours-long pipeline this skill exists to be the cheap alternative to.
You may also adjust the script's AI Tells subscore by up to ±15 points based on what was
actually read (regexes can't catch tone; readers can).
Every finding kept must have: category, `file:line`, a one-line description, and a
severity (minor 1-3 pts / moderate 4-7 pts / major 8-12 pts within its category).
No vibes-only deductions — if you can't cite a line, it isn't a finding.
### 3.5 Verify the receipts
Before scoring, re-open the cited location of every **major** finding (and anything
secondhand from a reviewer that sounds too good to roast with) and confirm the code
actually shows what the description claims. A wrong receipt is the one unforgivable
failure in a report that roasts people's code — drop or downgrade anything that doesn't
hold up exactly as described.
### 4. Compute the Slop Percentage
Follow `references/SCORING.md` exactly: seven weighted categories combine into one Slop
Percentage, which maps to a tier. Higher % = more slop = lower tier.
### 5. Generate the report and serve it
You never read or write HTML — a script does the injection, so the only thing you author
is a small JSON payload:
1. Write the payload to `<target-root>/.slop-check/report-data.json`, following
`references/REPORT-SCHEMA.md` (read it now).
2. Build the report (this validates the payload and fails loudly if something's missing):
```bash
node <this-skill's-directory>/scripts/build-report.mjs \
--data <target-root>/.slop-check/report-data.json \
--out <target-root>/slop-report.html
```
`build-report.mjs` prints `verified the live report renders this payload` on success.
If it instead prints a validation or verification error, fix what it names and rerun —
do **not** serve an unverified file. (A serve of the raw template renders only blank
defaults; the build step is what makes the report real.)
3. Serve it at a local URL (run in the background so you can keep working):
```bash
node <this-skill's-directory>/scripts/serve-report.mjs <target-root>/slop-report.html
```
Before handing over the URL, sanity-check that the served page carries the real data,
not template defaults: `curl -s <url> | grep -c '"name": "example-project"'` must
print `0`. If it prints `1`, the build didn't land — stop and fix it, don't give the
user a blank report.
It prints `Slop report live at: http://localhost:<port>` — give the user that URL.
If running a server isn't possible in the environment, fall back to opening the file
directly (`open` / `xdg-open`) or just tell the user the file path; the report is fully
self-contained either way.
The report includes **Fix-It Prompts**: for each of the top 3-6 findings, write a
ready-to-paste prompt the user can give to any coding agent to fix that exact issue.
These prompts are the genuinely-useful payoff; don't phone them in. Each prompt has
three parts:
1. **The task** — the files, the problem, the desired end state, and how to verify
nothing broke.
2. **Pre-paid context** — a short "Context from the slop-check map:" block embedding
what this run already learned, so the fixing agent starts warm instead of re-exploring:
the target file's `importedBy` list from `slop-map.json` (the blast radius), what it
imports, relevant reviewer observations about it and its neighbors, and any related
findings. This is the whole point — the tokens were spent during the check, so the
fix prompt should hand the knowledge over rather than make the next agent buy it again.
3. **The map pointer** — end with: "A machine-readable import map of this repo is at
`.slop-check/slop-map.json` — check a file's `importedBy` entry before moving or
renaming anything."
### 6. Deliver the verdict in the chat
End with a short verdict, in this shape:
```
🍝 Slop Check: 61% slop — "Somehow, It Works"
Scanned: <N> files · <N> lines · <cycles> cycles · <dup>% duplication · <tells> AI tells
Worst offenders: <top 3 findings, one line each, with file:line>
Most valuable fix: <the single highest-impact action, in plain terms>
Report: http://localhost:<port> (also saved to slop-report.html)
```
## Tone rules
- Straight-talking, deadpan, funny in the verdict copy — never mean about the *person*, only the code.
- Brutal honesty cuts both ways: if the codebase is genuinely good, say so plainly and grade it high. A rigged roast is worthless.
- Small hand-written hobby projects get judged on the same scale — but say what the scale is measuring so a 200-line script isn't confused about why "no layers" cost it nothing.
## Bundled resources
- `references/HEURISTICS.md` — the smell catalog for the taste pass (read during step 3)
- `references/SCORING.md` — category weights, formulas, tier bands, easter egg rule (read during step 4)
- `references/REPORT-SCHEMA.md` — the report payload format (read during step 5)
- `scripts/slop-scan.mjs` — deterministic metrics scanner (execute, don't read)
- `scripts/build-report.mjs` — injects your payload into the template (execute, don't read)
- `scripts/serve-report.mjs` — single-file report server (execute, don't read)
- `assets/report-template.html` — the report card template (never read this; build-report.mjs handles it)
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit intent, inputs, decision points, output contract, and outcome signal sections; clarified all edge cases (truncation, orphan files, receipt verification, report validation, server fallback, blank template detection); expanded procedure steps with numbered substeps and decision branches; documented the fix-it prompt structure in detail; kept original author's tone and procedure intact.
---
name: slop-check
description: Grade how vibe-coded a codebase is. Produces a Slop Percentage (0-100% AI slop), a tier ranking from Senior Engineer down to "GPT-3.5, Unsupervised", and an HTML report card with file:line findings and fix-it prompts.
---
# slop-check
Grade a codebase's slop level. Fun on the surface, real code review underneath: every point of slop must cite a real file and line. The roast is the headline; the receipts are the product.
## intent
Use this skill to audit any codebase and get back a numerical slop score (0-100%), a tier ranking, and an actionable HTML report with specific findings and copy-paste fix-it prompts for any coding agent. Invoke it whenever a user asks how vibe-coded / AI-generated / sloppy / well-architected a codebase is, wants a code quality score, roast, audit, or report card, or mentions AI slop, vibe coding, or code smells. Even if they don't name the skill, slop-check is the move.
The skill requires Node 18+ and nothing else. It scans deterministically, optionally spawns parallel reviewers for larger repos, computes a weighted score, and serves a report at a local URL.
## inputs
**Environment & Setup:**
- Node 18 or higher, available at the command line
- Target repo: passed as an argument, or defaults to current working directory
- No external API keys, auth, or service dependencies required
**Internal resources** (bundled with this skill):
- `references/HEURISTICS.md` - the smell catalog for the taste pass (read during step 3)
- `references/SCORING.md` - category weights, formulas, tier bands (read during step 4)
- `references/REPORT-SCHEMA.md` - the report payload format (read during step 5)
- `scripts/slop-scan.mjs` - deterministic metrics scanner
- `scripts/build-report.mjs` - injects your payload into the template
- `scripts/serve-report.mjs` - single-file report server
- `assets/report-template.html` - the report card template
**Target constraints:**
- Minimum 5 code files to grade. Fewer than that, stop and tell the user there isn't enough to audit.
- If the repo walk exceeds 50,000 code files, the scan truncates. Flag this in the verdict.
## procedure
### step 1: resolve and validate the target
1. Accept the target repo path as an argument, or use the current working directory as the default.
2. Count code files in the target (any file in a language the scanner recognizes).
3. **Decision: if fewer than 5 code files exist**, output "Not enough code to grade (need 5+)" and stop.
4. **Output from this step:** confirmed target path and file count.
### step 2: run the deterministic scanner
1. Execute:
```bash
node "<this-skill's-directory>/scripts/slop-scan.mjs" "<target-root>" --out "<target-root>/.slop-check/metrics.json"
(Always double-quote every path to handle spaces.) 2. Wait for the command to complete. The scanner produces:
<target-root>/.slop-check/metrics.json - the main metrics payload<target-root>/.slop-check/slop-map.json - the per-file import graph (for step 5)metrics.json before moving on. Extract:sampleSuggestions array (files most worth reading by hand in step 3)truncated: true, note in the final verdict that the scan hit the 50k-file cap and is a partial snapshot.metrics.json object, in-memory, and the sampleSuggestions list.Read references/HEURISTICS.md now if you haven't already. The four categories are:
Decision: scale effort to repo size:
Small repo (under ~40 code files): Read the sampleSuggestions files yourself. No subagents.
Larger repo with parallel subagent support: Spawn reviewers in one parallel batch, at most 6. Assign by lens:
If any lens's file list exceeds ~40 files, split it across two reviewers with the same lens. Do not spawn more than 6 or a second wave.
No subagent support: Read the sample files yourself, sequentially, using the three lenses.
For each file in the sample:
{ category, file, line, severity, description }{ file, observation } - one line per file, capturing what it is and how it relates to neighborsIf using subagents, collect their JSON output, merge findings, dedupe (if two reviewers caught the same thing), and own the final category scores.
You may adjust the script's AI Tells subscore by up to ±15 points based on what was read (regexes miss tone).
Output from this step: a findings list and per-file observations, organized by category.
references/SCORING.md now.slopPercentage (integer 0-100) and tier (string).references/REPORT-SCHEMA.md exactly.importedBy from slop-map.json, what the file imports, reviewer observations, related findings.slop-check/slop-map.json , check a file's importedBy entry before moving or renaming anything."<target-root>/.slop-check/report-data.json.node "<this-skill's-directory>/scripts/build-report.mjs" \
--data "<target-root>/.slop-check/report-data.json" \
--out "<target-root>/slop-report.html"
node "<this-skill's-directory>/scripts/serve-report.mjs" "<target-root>/slop-report.html"
open / xdg-open) or just hand the user the file path.curl -s <url> | grep -c '"name": "example-project"'
1, the build didn't land. Stop and fix it; don't give the user a blank report. If it outputs 0, the real data is there.Output a short verdict in this shape:
🍝 Slop Check: <slop %>% slop , "<tier>"
Scanned: <N> files · <N> lines · <cycles> cycles · <dup>% duplication · <tells> AI tells
Worst offenders: <top 3 findings, one line each, file:line>
Most valuable fix: <the single highest-impact action, in plain terms>
Report: <url or file path>
Minimum codebase size: If the target has fewer than 5 code files, stop immediately and tell the user "Not enough code to grade (need 5+)."
Truncation: If metrics.json has truncated: true, note in the verdict that the scan hit the 50k-file cap and is a partial snapshot.
Orphan files: Treat orphans from the scanner as suspects, not convictions. Dynamic loading, workers, and cross-package imports can hide real users. Only penalize if suspicious.
Subagent strategy: For repos with ~40+ code files and parallel support, spawn at most 6 reviewers in one batch. Split large lenses (>40 files) across two reviewers. Never spawn a second wave or a seventh reviewer.
No subagent support: Run the three lenses yourself sequentially over the same sample.
Receipt verification: Before scoring, re-open every major finding and confirm the code at file:line actually shows what was claimed. Drop or downgrade any finding that doesn't hold up exactly.
AI Tells adjustment: You may adjust the script's AI Tells subscore by up to ±15 points based on what was actually read (regexes can't catch tone; readers can).
Report build failure: If build-report.mjs prints a validation error, fix it and rerun. Never serve an unverified report.
Server unavailable: If you can't run a local server, fall back to opening the file directly or handing the user the file path. The report is self-contained either way.
Blank report: Before giving the user the URL, run a sanity check with curl. If the template defaults appear instead of real data, the build didn't land. Stop and fix it.
Files created:
<target-root>/.slop-check/metrics.json - the raw metrics payload from the scanner (file inventory, import graph metrics, AI-tell counts, subscores, sample suggestions)<target-root>/.slop-check/slop-map.json - the full per-file import graph (every file's importedBy / imports lists and flags; used by fix-it prompts and future fixing agents)<target-root>/.slop-check/report-data.json - the JSON payload for the HTML report (findings, observations, fix-it prompts, scores)<target-root>/slop-report.html - the final HTML report card (self-contained, ready to serve or open)Report data format: Follows references/REPORT-SCHEMA.md exactly. Includes:
slopPercentage (integer 0-100)tier (string, e.g. "Senior Engineer")findings (array of { category, file, line, severity, description })observations (object mapping file paths to one-line descriptions)fixItPrompts (array of 3-6 ready-to-paste prompts for coding agents)Live report: Served at http://localhost:<port> (exact port printed by serve-report.mjs) or accessible as a file at <target-root>/slop-report.html.
No partial or unverified reports: The build step validates the payload and fails loudly if anything is missing. Only serve a report that has been verified by build-report.mjs.
The user knows this skill worked when:
They receive a live URL or file path they can open in a browser and see a styled HTML report card with:
.slop-check/slop-map.json file for deeper explorationThe verdict in chat includes the slop percentage, tier, top 3 worst offenders (with file:line), the single most valuable fix, and a link to the report.
They can read any finding's file:line in their editor and confirm the code is exactly as described. No wrong receipts.
They can copy a Fix-It Prompt into any coding agent and the agent starts with knowledge of the repo's import graph, dependencies, and context , because the tokens were spent during the check and handed forward.
credits: original skill from clawhub; enriched and standardized for implexa quality standards. ```