# Contributing > Where to change skill references, scanner logic, catalogue data, or site components while keeping skill and website taxonomy aligned. - 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` - `skill/references/taxonomy.md` - `website/src/pages/index.astro` --- --- title: "Contributing" description: "Where to change skill references, scanner logic, catalogue data, or site components while keeping skill and website taxonomy aligned." --- Kill AI Slop is two sibling trees under one repo: `website/` (Astro field guide) and `skill/` (`kill-ai-slop` agent skill + dependency-free scanner). Taxonomy is shared in language and intent, but **not** generated from a single runtime module—site data lives in `website/src/data/catalogue.ts`, while the skill enforces the same 23 tells through `skill/references/*` and the `TELLS` table in `skill/scripts/scan.mjs`. Contributions that touch a tell must update every layer that still carries it. ## Repository surfaces ``` website/ Astro site, the field guide (multilingual, static, zero-JS-by-default) skill/ the kill-ai-slop Agent Skill (SKILL.md + references + scanner) ``` | Surface | Role | Primary paths | | --- | --- | --- | | Field guide | Catalogues 23 tells with before→after HTML demos; locales EN / ZH / JA / KO | `website/src/data/catalogue.ts`, `website/src/pages/index.astro`, styles under `website/src/styles/` | | Agent skill | Scan → triage → report → fix workflow for coding agents | `skill/SKILL.md`, `skill/references/`, `skill/scripts/scan.mjs` | | Standalone scanner | Greps code-level signals; **never edits files** | `skill/scripts/scan.mjs` (also invoked as `node skill/scripts/scan.mjs ` from repo root) | `website/src/data/catalogue.ts` is documented as the **single source of truth for the website** and the **spec the skill enforces**. The skill still keeps its own prose and pattern files; do not assume editing the catalogue alone updates detection or remediation. ## Where to change what | Intent | Edit these | Leave alone unless needed | | --- | --- | --- | | Tell copy, groups, tiers, detect chips (site) | `website/src/data/catalogue.ts` (`Entry`, `GROUPS`, `rawEntries`) | Scanner patterns until detection actually changes | | JA / KO catalogue strings | `catalogue.i18n.ts` (merged in; `zh` stays inline in `catalogue.ts`) | English-only demo HTML unless copy is in the demo | | Before→after demo | Demo payload keyed by `Entry.demo` (catalogue comments: demos / BeforeAfter data) | Skill workflow | | What / why / fix narrative for agents | `skill/references/taxonomy.md` | Site components | | Regex / greppable signals | `skill/scripts/scan.mjs` `TELLS[].patterns` **and** `skill/references/detection.md` | UI chrome | | Remediation before→after for agents | `skill/references/fixes.md` | Scanner (unless pattern list changes) | | Skill lifecycle, guardrails, report format | `skill/SKILL.md` | Catalogue entry fields | | Field-guide page structure, principles block, CTAs | `website/src/pages/index.astro` (`Base`, `T`, `SlopEntry`, `catalogue` import) | Scanner | | Design self-constraints (paper/ink, one editorial red, no gradient/emoji/glass/badge defaults) | `website/src/styles/tokens.css` (and related global styles) | Tell taxonomy unless a new visual rule becomes a tell | ### Catalogue entry shape (site) ```ts export type Group = "color" | "type" | "copy" | "component" | "layout" | "evolved"; export interface Bi { en: string; zh: string; ja?: string; ko?: string; } export interface Entry { id: string; // slug, e.g. "indigo-violet-gradient" n: number; // assigned by position in rawEntries tier: 1 | 2; // classic vs evolved group: Group; title: Bi; what: Bi; why: Bi; fix: Bi; detect: string[]; // mono chips + skill heuristics text demo?: string; // key into demos / BeforeAfter data } ``` - English is always required on `Bi`; other locales fall back to English at the `` layer. - `n` is renumbered from array order—inserting an entry renumbers later tells automatically on the site. - `detect` chips are human-readable signals (for example `"bg-clip-text text-transparent"`), not the same structure as scanner regexes. ### Scanner tell shape (skill) Each scanner tell is an object in the `TELLS` array inside `skill/scripts/scan.mjs`: | Field | Meaning | | --- | --- | | `id` | Zero-padded numeric string (`"01"` …), aligned with taxonomy numbering | | `group` | e.g. `color`, `type`, `copy`, `component`, `layout` | | `name` | Short human label for reports | | `fix` | One-line clean alternative | | `patterns` | Line-level regexes | | `copy: true` | Optional; copy tells also scan prose-oriented files | CLI (from skill directory or via repo-root path): ```bash node scan.mjs [root] [--json] [--no-color] # repo-root form: node skill/scripts/scan.mjs path/to/project node skill/scripts/scan.mjs path/to/project --json ``` Hard constraints encoded in the scanner header and skill workflow: - Pure Node—no dependencies. - **Never edits files**; every hit is a lead to confirm by reading code. - Default root is `.` if omitted. - Skips dirs such as `node_modules`, `.git`, `dist`, `build`, `out`, `.next`, `.astro`, coverage/vendor/cache deploy caches. - Scans extensions including `.html`, `.css`, framework SFC/JS/TS, `.md`, `.mdx`. ## Keep taxonomy aligned There are **two ID systems** that must stay mappable for the same tell: | Layer | Identifier style | Example | | --- | --- | --- | | Site catalogue | Kebab slug | `indigo-violet-gradient`, `gradient-text`, `mono-hue-alert` | | Taxonomy + scanner | Two-digit ordinal | `01` indigo→violet gradient, `02` gradient-clip headline | | Groups | Shared vocabulary | `color`, `type`, `copy`, `component`, `layout` (+ site `evolved` group / tier 2) | ```text website/src/data/catalogue.ts skill/references/taxonomy.md id: "indigo-violet-gradient" ↔ **01 · Indigo→violet gradient** detect: [chips...] ↔ skill/references/detection.md fix: Bi copy ↔ skill/references/fixes.md demo: "indigo-violet-gradient" skill/scripts/scan.mjs id: "01", patterns: [...] ``` Updating only `catalogue.ts` or only `scan.mjs` desyncs the field guide from the agent skill. Treat a tell as a cross-package unit: site entry + demo + i18n, taxonomy prose, detection patterns, fix playbook, and scanner `TELLS` row. ### Alignment checklist for one tell When adding or materially changing a tell: 1. **Site SSOT** — `rawEntries` row: stable `id`, `tier`, `group`, `title` / `what` / `why` / `fix` (`en` + `zh`), `detect[]`, `demo` key. 2. **Locales** — JA/KO in `catalogue.i18n.ts` if those locales should not fall back to English. 3. **Demo** — plain-HTML before→after for that `demo` key (site rebuilds tells in HTML; no reliance on live product screenshots). 4. **Skill taxonomy** — matching numbered entry in `skill/references/taxonomy.md` (what / why / fix; same decision rule: slop is absence of a decision). 5. **Detection** — concrete patterns in `skill/references/detection.md` and regexes in `TELLS` for the same ordinal `id`. 6. **Fixes** — before→after remediation in `skill/references/fixes.md` consistent with catalogue `fix` and site demo “after”. 7. **Principles** — if the change alters a global principle, update both `skill/SKILL.md` principles and the `principles` array in `website/src/pages/index.astro` (they currently mirror each other). ## Change recipes ### Add or update a catalogue tell (site + skill) Append or edit an object in `rawEntries` in `website/src/data/catalogue.ts`. Prefer a stable slug `id`. Set `tier` (`1` classic / `2` evolved) and `group`. Fill `detect` with the same code-level signals agents and scanners should recognize. Keep `en` complete. Put `zh` inline; merge `ja` / `ko` via `catalogue.i18n.ts`. Point `demo` at a plain-HTML before→after pair used by the index catalogue section. Add or revise the matching **NN** entry in `references/taxonomy.md`, pattern notes in `references/detection.md`, remediation in `references/fixes.md`, and a `TELLS` object with the same ordinal `id` and regexes in `scripts/scan.mjs`. `website/src/pages/index.astro` already imports `{ catalogue }` and renders entries through `SlopEntry`. Prefer data changes over hardcoding a one-off tell on the page. Run the site and the scanner (commands below). Confirm the new tell appears in the catalogue UI and produces expected hits on a fixture path—or zero hits on a clean control. ### Change detection only Edit: 1. `skill/scripts/scan.mjs` — `TELLS[n].patterns` (and `copy: true` if the tell is copy-oriented). 2. `skill/references/detection.md` — human pattern list + false positives. 3. Optionally `Entry.detect` chips in `catalogue.ts` so the field guide still matches what agents look for. Do **not** change scanner I/O flags or claim file mutation. Re-run: ```bash node skill/scripts/scan.mjs path/to/project node skill/scripts/scan.mjs path/to/project --json ``` ### Change skill workflow or guardrails Edit `skill/SKILL.md` only when changing host behavior: | Section | Contract | | --- | --- | | Workflow 1–5 | Scope → Scan → Triage → Report → Fix; **no mass-edit before the user sees the report** | | Scan command | `node scripts/scan.mjs ` / `--json`; pure Node; never edits | | Triage | Slop vs intentional; keep defended brand choices | | Report format | Grouped `slop file:line tell → fix` then ask which groups to apply | | Guardrails | Respect authorship; small diffs; no `git add -A`; no new dependencies; visual verify when possible | | References | Points at `taxonomy.md`, `detection.md`, `fixes.md`, `scripts/scan.mjs` | Install paths for consumers (document, don’t reinvent): ```bash npx skills add yetone/kill-ai-slop ``` Manual: copy everything under `skill/` into a `kill-ai-slop/` folder in the agent’s skills directory (see root README / `skill/README.md`). ### Change field-guide UI or principles | Piece | Path | | --- | --- | | Page sections (hero, definition, catalogue, skill CTA) | `website/src/pages/index.astro` | | Layout / i18n component / entry card | `Base.astro`, `T.astro`, `SlopEntry.astro` (imported from the index) | | Catalogue data binding | `import { catalogue } from "../data/catalogue"` | | Design tokens | `website/src/styles/tokens.css` — paper + ink, **one** editorial red, hierarchy from scale/space, hairline rules; no gradients / emoji / glass / badges | Local site loop: ```bash cd website npm install npm run dev # http://localhost:4321 npm run build # → dist/ (static, deploy anywhere) ``` ## Local verification signals | Change | Success signal | Failure / recovery | | --- | --- | --- | | Catalogue / site | `npm run dev` serves index; catalogue section lists 23 tells with working before→after toggles | Fix data shape / missing `demo` key; rebuild after i18n merge issues | | Scanner patterns | Grouped report or `--json` shows expected `file:line` for fixtures; count drops after intentional clean fixes | Confirm hits by reading code—scanner is a map, not gospel; tighten false positives in patterns + `detection.md` | | Skill docs | Workflow still forbids silent bulk edits; references still resolve under `skill/references/` | Restore report-before-fix ordering in `SKILL.md` | | Taxonomy sync | Same tell name/group/fix intent across catalogue `fix`, taxonomy, fixes, and scanner `fix` one-liner | Diff the four layers for that ordinal/slug pair | After any tell change, re-run the scanner on a known-sloppy fixture and a clean control, and open the local field guide entry for the same tell. Site demo “after” and `fixes.md` should describe the same clean move. ## Contribution constraints (repo-encoded) - **Scanner never writes files.** Fixes go through an agent host following `SKILL.md`, or through human edits—not through `scan.mjs`. - **No new dependencies** for skill/scanner work; site deps stay under `website/` via `npm install`. - **Demos are reconstructions** in plain HTML for education—not dunks on specific products. - **Slop vs intentional:** a tell is only slop when it is an unchosen default; keep defended brand choices. - **Design system of the guide** must not reintroduce catalogued slop (gradients, emoji spam, glass, badge walls, multi-hue candy semantics). ## What this page does not define Evidence here does not include PR templates, CI, license text, or automated tests that gate merges. Treat alignment as a maintainer checklist against the paths above until such automation appears in-repo. ## Related pages How catalogue.ts acts as site SSOT, how demos and i18n attach, and boundaries with skill references. Step-level add/update path for a tell: data, i18n, demo, skill taxonomy, detection, and fixes. Code-level signals and how findings map back to taxonomy ids. Invocation, flags, walk/scan behavior, and the no-edit constraint. Per-tell clean fixes and how demos illustrate preferred outcomes. Paper/ink palette, single editorial red, and banned slop defaults for the site itself. Static build to dist and deploy-anywhere assumptions for the field guide.