# Overview

> What Kill AI Slop exposes: the agent skill, scanner entry points, shared catalogue, and field-guide site, plus who should use which surface first.

- Repository: yetone/kill-ai-slop
- GitHub: https://github.com/yetone/kill-ai-slop
- Human docs: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb
- Complete Markdown: https://grok-wiki.com/public/docs/yetone-kill-ai-slop-c0d8c9670cbb/llms-full.txt

## Source Files

- `README.md`
- `skill/SKILL.md`
- `skill/scripts/scan.mjs`
- `website/src/data/catalogue.ts`
- `website/src/pages/index.astro`

---

---
title: "Overview"
description: "What Kill AI Slop exposes: the agent skill, scanner entry points, shared catalogue, and field-guide site, plus who should use which surface first."
---

**Kill AI Slop** (`yetone/kill-ai-slop`) is a two-surface repo: a static multilingual Astro field guide under `website/`, and a portable agent skill under `skill/` (`name: kill-ai-slop`) with a dependency-free scanner at `skill/scripts/scan.mjs`. Both surfaces share one 23-tell taxonomy; the website catalogue at `website/src/data/catalogue.ts` is the documented single source of truth the skill enforces.

## Product surfaces

| Surface | Path | Role | Edits project files? |
| --- | --- | --- | --- |
| Field guide site | `website/` | Multilingual catalogue (en/zh/ja/ko), before→after HTML demos, principles | No |
| Agent skill | `skill/SKILL.md` + `skill/references/` | Scan → triage → report → propose/apply fixes in a coding-agent host | Only when the host applies fixes after the report |
| Scanner CLI | `skill/scripts/scan.mjs` | Greps frontend source for code-level signals; grouped or JSON report | **Never** |

```mermaid
flowchart TB
  subgraph repo["yetone/kill-ai-slop"]
    subgraph site["website/"]
      cat["src/data/catalogue.ts\n23 tells · tier · group · detect · demo"]
      index["src/pages/index.astro\nfield guide UI"]
      tokens["src/styles/tokens.css\npaper + ink self-rules"]
    end
    subgraph skillPack["skill/"]
      skillmd["SKILL.md\nworkflow + guardrails"]
      refs["references/\ntaxonomy · detection · fixes"]
      scan["scripts/scan.mjs\nTELS[] patterns"]
    end
  end
  cat -->|"taxonomy / detect chips"| index
  cat -->|"spec the skill enforces"| skillmd
  skillmd --> refs
  skillmd -->|"run for leads"| scan
  scan -->|"file:line hits only"| skillmd
```

Live field guide: [killaislop.com](https://killaislop.com).

## Who should use which surface first

| Goal | Start here | Then |
| --- | --- | --- |
| Learn what each tell looks like and the clean alternative | Field guide (`website/`, or killaislop.com) | Scan a real project |
| Clean a vibe-coded UI/docs project with an agent | Install skill → invoke with “kill the AI slop in this project” | Host runs scanner, triage, report, then fix |
| Get a machine-readable hit map without an agent | `node skill/scripts/scan.mjs <root> [--json]` | Confirm hits by reading code; map to fixes |
| Add or change a tell | Update catalogue entry (+ i18n/demo as needed) and keep skill refs/scanner aligned | See extend-catalogue and contributing pages |

<Info>
The standalone scanner never edits files. Mass edits happen only in an agent host after the user has seen the report and approved groups to apply (`skill/SKILL.md` workflow).
</Info>

## Repo layout

```
website/   Astro site — field guide (multilingual, static, zero-JS-by-default)
skill/     kill-ai-slop Agent Skill (SKILL.md + references + scanner)
```

### Website (`website/`)

- Stack: Astro, static build to `dist/`, deploy anywhere.
- Local:

```bash
cd website
npm install
npm run dev        # http://localhost:4321
npm run build      # → dist/
```

- Design self-constraints (README): paper + ink, **one** editorial red, hierarchy from scale and space, hairline rules; no gradients / emoji / glass / badges. Rules live in `website/src/styles/tokens.css`.
- Index (`website/src/pages/index.astro`) loads `catalogue` and renders each entry via `SlopEntry`; sections include definition, catalogue (23 tells), and six principles.

### Skill (`skill/`)

- Skill id: `kill-ai-slop`.
- Host install (universal):

```
npx skills add yetone/kill-ai-slop
```

- Manual: copy `skill/` contents into the agent’s `kill-ai-slop/` skills directory (see repo README / `skill/README.md` for host-specific paths).
- Works on HTML/CSS, React/Vue/Svelte/Astro, Tailwind, and Markdown copy (skill description).
- Provider-neutral: the skill is files on disk (SKILL.md + references + scanner). Any Agent-Skills-compatible host can load it; no model-provider or hosted connector is required.

### Scanner (`skill/scripts/scan.mjs`)

```bash
node skill/scripts/scan.mjs path/to/project          # grouped report
node skill/scripts/scan.mjs path/to/project --json    # machine-readable
```

| CLI | Behavior |
| --- | --- |
| `[root]` | Project root; default `.` |
| `--json` | Machine-readable output for triage |
| `--no-color` | Disable ANSI color (also off when not a TTY or when `--json`) |

Constraints from the scanner header and skill workflow:

- Pure Node (`node:fs` / `node:path` only); no package dependencies.
- **Never edits files.** Hits are leads to confirm by reading code, not verdicts.
- Walks frontend extensions (`.html`, `.css`, `.scss`, `.sass`, `.less`, `.tsx`/`.jsx`/`.ts`/`.js`/`.mjs`/`.cjs`, `.vue`, `.svelte`, `.astro`, `.md`, `.mdx`, plus `tailwind.config.*`).
- Skips dirs such as `node_modules`, `.git`, `dist`, `build`, `out`, `.next`, `.astro`, coverage, vendor, lockfiles, minified `*.min.js|css`, and files larger than 512 KiB.

## Shared taxonomy: 23 tells

Both the site and the skill operate on **23** AI-slop tells.

### Catalogue model (`website/src/data/catalogue.ts`)

Documented as the single source of truth for the website and the spec the skill enforces.

| Field | Type / notes |
| --- | --- |
| `id` | String slug (e.g. `indigo-violet-gradient`) |
| `n` | Position number (auto from array order) |
| `tier` | `1` classic · `2` evolved |
| `group` | `color` \| `type` \| `copy` \| `component` \| `layout` \| `evolved` |
| `title` / `what` / `why` / `fix` | Localized `Bi` (`en` required; `zh` inline; `ja`/`ko` optional, merged from `catalogue.i18n.ts`) |
| `detect` | Code-level signal chips shared with skill heuristics |
| `demo?` | Key into demo HTML / before→after data |

### Scanner tell table (`skill/scripts/scan.mjs` `TELLS`)

Numeric ids `01`–`23`, with `group`, human `name`, one-line `fix`, and regex `patterns`. Some tells set `copy: true` so they also scan prose files.

| Group | Scanner examples (id · name) |
| --- | --- |
| `color` | `01` indigo→violet gradient · `02` gradient-clip headline · `03` warm cozy palette · `04` default semantic palette · `05` one-hue status box · `06` gradients as atmosphere |
| `type` | `07` serif-italic emphasis · `08` serif where sans belongs · `09` decorative strikes & highlights |
| `copy` | `10` highlighted keywords · `11` AI copywriting voice · `12` emoji everywhere |
| `component` | `13`–`21` (glowing status dot, left-border callout, pastel icon tiles, max-radius/glass, shadows, nested corners, badge spam, AI SVG icon, icon-in-tint) |
| `layout` | `22` all-caps card grid |
| `evolved` | `23` tasteful-terminal |

<Note>
Catalogue string ids and scanner numeric ids describe the same 23-tell set; keep names, groups, and detect patterns aligned when extending the catalogue.
</Note>

## Agent skill lifecycle

From `skill/SKILL.md` — run in order; do not mass-edit before the user sees the report.

```mermaid
stateDiagram-v2
  [*] --> Scope
  Scope --> Scan: confirm roots; skip build artifacts
  Scan --> Triage: scan.mjs hits as map
  Triage --> Report: slop vs intentional
  Report --> Fix: user picks groups / all
  Fix --> Scan: re-run; count should drop
  Report --> [*]: user stops without apply
```

1. **Scope** — Default app/site source; skip `node_modules`, `dist`, `build`, `.git`, vendor, lockfiles, minified files. Ask if multiple apps are mixed.
2. **Scan** — `node scripts/scan.mjs <root>` or `--json`.
3. **Triage** — Open each hit; keep deliberate brand/authorship; flag machine defaults. Use `references/taxonomy.md` and `references/detection.md`.
4. **Report** — Grouped summary before any write: tell, `file:line`, why, proposed fix. Ask which groups to apply.
5. **Fix** — Minimal change via `references/fixes.md`; prefer shared tokens/components; no new brand colors without user confirm; re-scan after.

### Guardrails

- Respect authorship; ask when unsure.
- Small reviewable diffs; never `git add -A`.
- No new dependencies to do the work.
- Visual check when a dev server exists; a clean scan ≠ a better page.

### Skill references

| Path | Contents |
| --- | --- |
| `references/taxonomy.md` | 23 tells: what, why slop, fix |
| `references/detection.md` | ripgrep/regex patterns + false positives |
| `references/fixes.md` | before→after remediation patterns |
| `scripts/scan.mjs` | Dependency-free scanner |

## Field guide content model

Index sections (from `index.astro`):

| Section | Purpose |
| --- | --- |
| Hero | Positioning + CTAs to `#catalogue` and `#skill` |
| Definition | What “AI slop” means in this project |
| Catalogue | 23 entries; classic vs evolved legend; before→after demos |
| Principles | Six anti-slop rules (same spine as skill principles) |

### Six principles (site + skill)

1. Decide before you decorate  
2. One accent, one voice  
3. Hierarchy from scale and space  
4. Subtract first  
5. Specific beats loud / punchy (copy)  
6. Decoration must mean something  

Demos are plain-HTML rebuilds for education, not screenshots of specific products (catalogue comments + README).

## Constraints and non-goals

| Constraint | Surface |
| --- | --- |
| Scanner never edits files | `scan.mjs` |
| Agent must report before mass fix | `SKILL.md` workflow |
| Zero-JS-by-default static site | `website/` README |
| Design system bans the tells it documents | `tokens.css` + site itself |
| Skill adds no new npm deps for cleanup | Guardrails |
| Hits are not automatic truth | Scanner + triage |

Out of scope for this overview: full CLI flag reference, per-tell regex lists, remediation playbooks, catalogue field schemas, and install variants — those are separate docs pages.

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Install the skill via npx or manual copy; set up website dependencies.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First scanner report and local field-guide run with success signals.
  </Card>
  <Card title="Slop taxonomy" href="/slop-taxonomy">
    Categories, named signals, and shared language across site and skill.
  </Card>
  <Card title="Catalogue model" href="/catalogue-model">
    How catalogue.ts is the single source of truth and how demos/i18n attach.
  </Card>
  <Card title="Skill workflow" href="/skill-workflow">
    Scan → triage → report → propose/apply without silent scanner edits.
  </Card>
  <Card title="Scanner CLI reference" href="/scanner-cli-reference">
    Invocation, --json, walk behavior, and the no-edit hard constraint.
  </Card>
</CardGroup>