# Use the agent skill

> Invoke kill-ai-slop inside a coding agent after install: prompts, expected host behavior, and how the skill uses references and the scanner.

- 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

- `skill/SKILL.md`
- `skill/README.md`
- `skill/scripts/scan.mjs`
- `skill/references/taxonomy.md`
- `README.md`

---

---
title: "Use the agent skill"
description: "Invoke kill-ai-slop inside a coding agent after install: prompts, expected host behavior, and how the skill uses references and the scanner."
---

After install, the `kill-ai-slop` Agent Skill is the host-driven path: the agent loads `skill/SKILL.md`, runs `scripts/scan.mjs` as a read-only map, triages hits against `references/`, reports before any edit, then proposes or applies fixes only for groups you approve.

<Info>
The skill is provider-neutral and portable: it is a directory of files (`SKILL.md`, `references/`, `scripts/scan.mjs`) that any Agent Skills host can load from its own skills path. No model vendor, hosted API, or proprietary connector is required.
</Info>

## Prerequisites

| Requirement | Detail |
|---|---|
| Skill installed | `kill-ai-slop/` under the host skills directory (project or user scope) |
| Node available | For the bundled scanner: `node scripts/scan.mjs …` |
| Target | A web UI / docs tree (HTML/CSS, React/Vue/Svelte/Astro, Tailwind, Markdown) |

Install paths and the `npx skills add yetone/kill-ai-slop` flow are documented on the installation page. This page assumes registration succeeded and the host can resolve the skill by name or description.

:::files
skill/
  SKILL.md                 # definition, workflow, guardrails
  references/
    taxonomy.md            # 23 tells: what / why / fix
    detection.md           # patterns + false positives
    fixes.md               # before→after remediation
  scripts/
    scan.mjs               # dependency-free scanner (never edits)
:::

## Invoke the skill

Once registered, start with a plain-language request. The skill’s frontmatter `description` is what hosts match on; these phrases are the intended triggers:

| Intent | Example prompts |
|---|---|
| Full de-slop pass | `Kill the AI slop in this project.` |
| Short forms | `de-slop this`, `remove the AI look`, `make this not look AI-generated` |
| Scope hints | Landing page / UI / docs that feel templated; clean up vibe-coded UI defaults |

You do not need to name files or pass flags unless you want a narrower root. The agent should confirm scope when the repo holds multiple apps.

```text
Kill the AI slop in this project.
```

```text
De-slop the marketing site under apps/web. Keep brand tokens.
```

## Expected host behavior

Hosts must follow the ordered workflow in `SKILL.md`. **Do not mass-edit before the user has seen the report.**

```mermaid
sequenceDiagram
  participant User
  participant Agent as Agent host<br/>(SKILL.md)
  participant Scan as scripts/scan.mjs
  participant Refs as references/*

  User->>Agent: kill AI slop / de-slop / remove AI look
  Agent->>User: 1. Scope (root; multi-app?)
  Agent->>Scan: node scripts/scan.mjs root [--json]
  Scan-->>Agent: grouped file:line hits (read-only)
  Agent->>Refs: taxonomy + detection (triage)
  Agent->>User: 4. Report + ask which groups
  User->>Agent: approve groups / all
  Agent->>Refs: fixes.md patterns
  Agent->>User: 5. Minimal diffs + re-scan note
```

### 1. Scope

- Default to app/site source.
- Skip noise dirs and artifacts the scanner also skips (`node_modules`, `dist`, `build`, `.git`, `vendor`, lockfiles, minified files, and the scanner’s own `SKIP_DIRS` set).
- Ask if the project mixes several apps before walking everything.

### 2. Scan

Run the bundled scanner (path relative to the installed skill directory):

```bash
node scripts/scan.mjs <root>          # human-readable report
node scripts/scan.mjs <root> --json   # machine-readable, for triage
```

| Property | Behavior |
|---|---|
| Runtime | Pure Node; no npm dependencies |
| Side effects | **Never edits files** |
| Role of output | Starting map of code-level signals, **not** verdicts |
| Confirmation | Every hit must be checked by reading the file |

From the repo root (without installing into the host), the same binary is:

```bash
node skill/scripts/scan.mjs path/to/project
node skill/scripts/scan.mjs path/to/project --json
```

Scanner CLI surface (as implemented in `scan.mjs`):

| Input | Default | Meaning |
|---|---|---|
| `[root]` | `.` | First non-flag argv path |
| `--json` | off | Machine-readable report |
| `--no-color` | off | Disable ANSI when not JSON |

Optional flags beyond those three are not part of the documented scanner contract.

### 3. Triage

For every hit, open the file and decide **slop vs intentional**. This is what separates the skill from a lint rule:

- Keep defended choices: brand tokens, logos, deliberate illustration, intentional serif/gradient/emoji.
- Flag **defaults** — “absence of a decision,” per `references/taxonomy.md`.
- Use `references/detection.md` for exact patterns and common false positives.

### 4. Report

**Before any edit**, emit a grouped summary: tell, confirmed `file:line`, one sentence why, proposed fix. Mirror this shape:

```text
slop  src/Hero.tsx:12   indigo→violet gradient        → one solid accent
slop  src/Hero.tsx:31   gradient-clip headline        → solid ink, scale up
slop  src/Note.tsx:8    border-l-4 callout ×3         → 1 aside, rest is body
slop  copy.md:1         "not just X — it's Y"         → say the specific thing
→ 4 groups, 11 hits.
```

Then ask which groups to apply, or whether to proceed on all.

### 5. Fix

Only after approval:

- Apply the **minimal** change that removes the tell while preserving intent and function.
- Use `references/fixes.md` for before→after patterns.
- Prefer shared tokens/components over every call site.
- **Never invent new brand colors**; if palette must change, propose neutrals + existing accent and wait for confirmation.
- Keep copy meaning; make it specific rather than deleting.
- Re-run the scanner; confirm hit count dropped; list intentional leftovers with reasons.

## How the skill uses references

| Path | Role in the agent loop |
|---|---|
| `SKILL.md` | Host skill entry: `name: kill-ai-slop`, trigger `description`, workflow, guardrails |
| `references/taxonomy.md` | 23 tells (classic + evolved): definition, why it reads machine-made, fix intent |
| `references/detection.md` | Concrete patterns + false positives for triage |
| `references/fixes.md` | Remediation before→after patterns when applying edits |
| `scripts/scan.mjs` | Automated lead generation only |

Taxonomy rule the agent must honor: a tell is slop only when it is a **default nobody chose**. The same element, chosen and defended, stays.

Coverage called out by the skill description (code and copy surfaces): indigo→violet gradients, gradient-clip headlines, warm cozy palettes, default semantic palette, one-hue status boxes, atmospheric gradients, serif-italic emphasis, serif-where-sans, decorative strikes/highlights, highlighted keywords, AI copywriting voice, emoji spam, glowing status dots, left-border callouts, pastel icon tiles, glass/over-rounding, oversized shadows, non-nesting corners, badge/pill spam, AI-drawn SVG icons, icon-in-tint tiles, all-caps card grids, and “tasteful terminal” — across HTML/CSS, React/Vue/Svelte/Astro, Tailwind, and Markdown.

## How the skill uses the scanner

The scanner is a **lead generator**, not the decision engine.

| Concern | Scanner | Agent (skill) |
|---|---|---|
| Walk sources | Yes (`walk`, extension filter, skip dirs) | Chooses `<root>` after Scope |
| Match patterns | Yes (`TELLS` regexes in `scan.mjs`) | Confirms / rejects each hit |
| Edit files | **No** | Yes, only after Report + approval |
| Intent / brand | No | Yes (triage + fixes playbook) |
| Visual QA | No | Yes when a dev server exists |

Internal constraints encoded in `scan.mjs` (for interpreting empty or sparse reports):

- Skips directories such as `node_modules`, `.git`, `dist`, `build`, `out`, `.next`, `.astro`, `.output`, `.svelte-kit`, `.nuxt`, `coverage`, `vendor`, `.cache`, `.vercel`, `.turbo`
- Scans extensions including `.html`, `.css`/`.scss`/`.sass`/`.less`, `.tsx`/`.jsx`/`.ts`/`.js`/`.mjs`/`.cjs`, `.vue`, `.svelte`, `.astro`, `.md`, `.mdx`, plus `tailwind.config.*`
- Skips `*.min.js` / `*.min.css`, lockfiles, and files larger than **512 KiB**
- Tells marked `copy: true` (e.g. AI voice, emoji) also consider prose-bearing files; others focus on code/style signals

<Warning>
A clean re-scan is not proof of a better page. `SKILL.md` requires visual verification when a dev server is available: before/after beats a zero hit count.
</Warning>

## Guardrails the host must enforce

| Rule | Constraint |
|---|---|
| Authorship | Unfamiliar files and deliberate flourishes are someone’s choice; when unsure, **ask** — do not strip |
| Diff size | No unrelated reformats; never `git add -A`; stage explicit files only |
| Dependencies | **No new packages** for de-slop work |
| Verification | Prefer visual check; re-scan and document intentional remaining hits |
| Order | Report → user choice → fix (no silent bulk edits from the skill path) |

Standalone scanner use (no skill host) is scan-only; it cannot apply fixes. Fix application is host-mediated via the skill workflow.

## Verification signals

| Stage | Success signal |
|---|---|
| Invoke | Host loads `kill-ai-slop` from skills path (not a free-form guess of the catalogue) |
| Scan | Grouped `file:line` report or JSON; process does not write project files |
| Report | Summary before edits; user asked which groups to apply |
| Fix | Small diffs; scanner count down; intentional leftovers listed with reasons |
| Visual | Page looks intentional under one accent / one voice, not just “lint clean” |

## Troubleshooting

| Symptom | Check |
|---|---|
| Skill never fires | Re-install registration; prompt with a description-matching phrase (“kill AI slop”, “de-slop”, “remove the AI look”) |
| Agent edits immediately | Workflow violation — require step 4 report and approval first |
| Scanner path not found | Run relative to the installed skill: `node scripts/scan.mjs …`, or from clone: `node skill/scripts/scan.mjs …` |
| Hits look wrong | Expected — treat as leads; re-read with `taxonomy.md` + `detection.md` false positives |
| Palette rewrite surprises | Agent must not invent brand colors; stop and confirm neutrals + existing accent |
| Multi-app monorepo noise | Re-scope to a single app root before scan |

## Next

<CardGroup>
  <Card title="Skill workflow" href="/skill-workflow">
    Lifecycle detail: scan → triage → report → propose/apply without silent scanner edits.
  </Card>
  <Card title="Scan a web project" href="/scan-web-project">
    Point the dependency-free scanner at a path; grouped vs JSON reports.
  </Card>
  <Card title="Apply clean fixes" href="/apply-clean-fixes">
    Map hits to the fixes playbook; propose vs apply in an agent host.
  </Card>
  <Card title="Scanner CLI reference" href="/scanner-cli-reference">
    Flags, walk/scan behavior, and the hard no-edit constraint.
  </Card>
  <Card title="Remediation playbook" href="/fixes-playbook">
    Per-tell clean fixes and before/after intent.
  </Card>
  <Card title="Installation" href="/installation">
    npx or manual copy into the host skills directory.
  </Card>
</CardGroup>