# Skill workflow
> Agent skill lifecycle: scan, triage, report, then propose or apply fixes without silent file edits from the standalone 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/scripts/scan.mjs`
- `skill/references/detection.md`
- `skill/references/fixes.md`
- `skill/README.md`
---
---
title: "Skill workflow"
description: "Agent skill lifecycle: scan, triage, report, then propose or apply fixes without silent file edits from the standalone scanner."
---
The `kill-ai-slop` agent skill (`skill/SKILL.md`) runs a fixed five-step lifecycle—**Scope → Scan → Triage → Report → Fix**—so a host agent detects AI-slop tells, confirms them against real intent, reports before any write, and only then proposes or applies minimal fixes. The bundled scanner `skill/scripts/scan.mjs` is read-only: it walks frontend source, matches tell patterns, and prints `file:line` hits (human or `--json`); it never edits files.
Do not mass-edit before the user has seen the report. Standalone `node scripts/scan.mjs` is a map of leads, not a verdict and not a mutator.
## Surfaces in play
| Surface | Path | Role in the lifecycle |
|---|---|---|
| Skill definition | `skill/SKILL.md` | Principles, ordered workflow, guardrails |
| Scanner | `skill/scripts/scan.mjs` | Dependency-free Node walk + regex match; report only |
| Taxonomy | `skill/references/taxonomy.md` | 23 tells: what each is, why it reads as slop, the fix |
| Detection reference | `skill/references/detection.md` | Patterns + common false positives (human reference; scanner encodes the patterns) |
| Fixes playbook | `skill/references/fixes.md` | Before→after directions per tell |
Trigger phrases the skill is meant for include: “kill AI slop”, “de-slop”, “remove the AI look”, “make this not look AI-generated”, or cleaning a templated landing page / UI / docs.
## Lifecycle at a glance
```mermaid
stateDiagram-v2
[*] --> Scope
Scope --> Scan: root confirmed
Scan --> Triage: file:line hits
Triage --> Report: confirmed slop only
Report --> AwaitingApproval: grouped summary shown
AwaitingApproval --> Fix: user picks groups / all
AwaitingApproval --> [*]: user declines
Fix --> Rescan: re-run scanner
Rescan --> [*]: counts dropped; leftovers noted
```
Ownership boundary: **scan/report stay read-only**; **writes happen only in Fix**, under host-agent control after user approval. The scanner process itself never crosses that boundary.
## Principles (held on every fix)
From `SKILL.md`, applied during triage and fix—not as optional style notes:
1. **Decide before you decorate.** Every visual choice must be explainable.
2. **One accent, one voice.**
3. **Hierarchy from scale and space.** Coloring words or swapping fonts is a shortcut.
4. **Subtract first.** First move toward not-ugly is removing things.
5. **Specific beats punchy** in copy.
6. **Decoration must mean something** — icons, badges, callouts are signals.
## Step-by-step workflow
Confirm what to scan. Default to app/site source. Skip `node_modules`, `dist`, `build`, `.git`, `vendor`, lockfiles, and minified files (the scanner also skips additional build caches such as `.next`, `.astro`, `.output`, `.svelte-kit`, `.nuxt`, `coverage`, `.cache`, `.vercel`, `.turbo`).
If the repo mixes several apps, ask which tree to target before scanning.
Run the bundled scanner for code-level signals of each tell and print grouped `file:line` hits:
```bash
node scripts/scan.mjs # human-readable report
node scripts/scan.mjs --json # machine-readable, for triage
```
From the skill directory, invocation is the same shape as documented on the scanner (`node scan.mjs [root] [--json] [--no-color]`). Defaults: `root` is `.` when omitted; color is on only when stdout is a TTY, not JSON, and `--no-color` is absent.
**Scanner contract**
| Fact | Behavior |
|---|---|
| Runtime | Pure Node (`node:fs`, `node:path` only)—no package install |
| Mutates files? | **Never** |
| Hit meaning | Lead to confirm by reading code, not a verdict |
| Large files | Skip files larger than `512 * 1024` bytes |
| Extensions | `.html .css .scss .sass .less .tsx .jsx .ts .js .mjs .cjs .vue .svelte .astro .md .mdx`, plus `tailwind.config.*` |
| Also skipped | `*.min.js` / `*.min.css`, lockfiles |
Each tell in `TELLS` has `id`, `group`, `name`, one-line `fix`, and `patterns`. Some copy-oriented tells set `copy: true` (ids `10`–`12`).
For every hit, open the file and decide **slop vs. intentional**. This step separates the skill from a lint rule.
- Keep brand tokens, logos, deliberate illustrations, and defended design choices.
- Flag defaults and pile-ons that lack intent.
- Use `references/taxonomy.md` for what the tell is and why it reads as machine-made.
- Use `references/detection.md` for exact patterns and common false positives.
Examples of “can be real choices”: a brand-true purple, a single deliberate hero gradient headline, emoji in a picker feature, serif for an editorial product.
**Before changing anything**, give a grouped summary: each tell, confirmed `file:line` hits, one sentence on why, and the proposed fix. Mirror this format:
```
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. Do not skip this gate.
Apply the **minimal** change that removes the tell while preserving intent and function. Use `references/fixes.md` for before→after direction per tell (adapt to project tokens/framework; not blind find-and-replace).
**Fix order of operations** (`fixes.md`):
1. Design tokens / theme first (colors, radius, fonts)—many hits disappear at once.
2. Shared components, then one-off call sites.
3. Copy last.
**Fix rules**
- Prefer shared tokens/components over every call site.
- Never invent new brand colors; if palette must change, propose neutrals + the project’s existing accent and wait for confirmation.
- Keep copy meaning; make it specific—don’t just delete it.
- Re-run the scanner after fixing; confirm hit count dropped; note intentional leftovers with reasons.
## Scanner vs agent skill
| | Standalone scanner | Agent skill host |
|---|---|---|
| Command / surface | `node scripts/scan.mjs [root] [--json] [--no-color]` | Host invokes skill after install; user prompt like “Kill the AI slop in this project” |
| Reads source | Yes | Yes (via scanner + file open) |
| Edits source | **No** | Only after report + user approval, in Fix |
| Output | Grouped human report or JSON | Same scan map, then triage narrative + proposal + optional apply |
| Judgment | Pattern match only | Slop vs intentional; false-positive handling |
Use `--json` when the host needs a machine-readable hit list for triage. Treat JSON hits the same as the human report: confirm by reading the code before proposing edits.
## Tell inventory (scanner `TELLS`)
Twenty-three tells, ids `01`–`23`, with groups used for reporting and prioritization:
| Group | IDs | Examples (name → one-line fix) |
|---|---|---|
| `color` | `01`–`06` | indigo→violet gradient → one solid, chosen accent |
| `type` | `07`–`09` | serif-italic emphasis → emphasise by weight, one voice |
| `copy` | `10`–`12` | AI copywriting voice → say the specific thing |
| `component` | `13`–`21` | left-border callout → one aside, rest is body |
| `layout` | `22` | all-caps card grid → show the one key thing fully |
| `evolved` | `23` | tasteful-terminal → mono for code only |
Full pattern lists live in `skill/scripts/scan.mjs` and the parallel human reference `skill/references/detection.md`.
## Guardrails
| Guardrail | Constraint |
|---|---|
| Respect authorship | Unfamiliar files and deliberate flourishes are someone’s choice; when unsure, ask—don’t strip |
| Small, reviewable diffs | No unrelated reformats; never `git add -A`; stage explicit files only |
| No new dependencies | Do not add packages to perform this work |
| Visual verify when possible | If a dev server exists, compare before/after; a clean scan ≠ a better page |
## Verification signals
| Stage | Success signal |
|---|---|
| Scan | Grouped `file:line` (or JSON) report; no files modified by the scanner |
| Triage | Each kept/discarded hit has a reason (intentional brand vs default) |
| Report | User sees groups + proposed fixes **before** any edit |
| Fix | Minimal diffs; preferred shared-token changes; scanner re-run shows lower counts |
| Leftovers | Intentionally retained hits documented with reason |
## Skill package layout
:::files
skill/
SKILL.md # workflow + guardrails
README.md # install + use
references/
taxonomy.md # 23 tells (what / why / fix)
detection.md # patterns + false positives
fixes.md # before→after remediation
scripts/
scan.mjs # dependency-free, read-only scanner
:::
## Related pages
Invoke kill-ai-slop in a coding agent after install: prompts and host behavior.
Point the scanner at a path; interpret grouped vs JSON reports.
Map hits to the fixes playbook; choose propose vs apply.
Invocation, flags, walk/scan behavior, and the hard no-edit constraint.
Code-level signals per tell and how findings map to taxonomy ids.
Per-tell clean fixes and preferred before/after outcomes.
Shared language for categories, named signals, and field-guide alignment.