v3.1.0: antislop-code skill, per-skill READMEs, tagline rename, bump
This commit is contained in:
miqdadbadzubair-design
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "anti-slop",
|
||||
"description": "The antislop skill/plugin: Anti AI Slop, Design & Copy Rules for AI coding agents.",
|
||||
"description": "The antislop skill/plugin. Anti Slop: Rules for AI Coding Agents.",
|
||||
"owner": {
|
||||
"name": "miqdadbadjuber"
|
||||
},
|
||||
@@ -8,8 +8,8 @@
|
||||
{
|
||||
"name": "antislop",
|
||||
"source": "./",
|
||||
"version": "3.0.2",
|
||||
"description": "Anti AI Slop: Design & Copy Rules. A rules filter for AI coding agents that stops generic AI slop UI and copy. Loads as five skills."
|
||||
"version": "3.1.0",
|
||||
"description": "Anti Slop: Rules for AI Coding Agents. Stops generic AI slop in generated UI, copy, and code. Loads as six skills."
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"name": "antislop",
|
||||
"displayName": "antislop",
|
||||
"version": "3.0.2",
|
||||
"description": "Anti AI Slop: Design & Copy Rules. A rules filter for AI coding agents that stops generic AI slop UI and copy. Loads as five skills.",
|
||||
"version": "3.1.0",
|
||||
"description": "Anti Slop: Rules for AI Coding Agents. Stops generic AI slop in generated UI, copy, and code. Loads as six skills.",
|
||||
"author": {
|
||||
"name": "miqdadbadjuber"
|
||||
},
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
# antislop
|
||||
|
||||
> **Anti AI Slop: Design & Copy Rules.** A rules file for AI coding agents. It stops them from generating generic "AI slop" UI and copy, without letting the result turn sterile. It is a **filter, not a style guide**: no prescribed colors, fonts, or layouts. It is not only for building pages: it also writes and audits copy, so AI text stops reading like AI. And it never beautifies on its own; `DESIGN.md` (yours) is where beauty and direction come from.
|
||||
> **Anti Slop: Rules for AI Coding Agents.** It stops them from generating generic "AI slop" UI and copy, without letting the result turn sterile. It is a **filter, not a style guide**: no prescribed colors, fonts, or layouts. It is not only for building pages: it also writes and audits copy, so AI text stops reading like AI. And it never beautifies on its own; `DESIGN.md` (yours) is where beauty and direction come from.
|
||||
|
||||
> **New here? Start with the [guide](guide.md).** It explains what antislop is and how to install it, from zero.
|
||||
|
||||
@@ -70,8 +70,9 @@ curl -o antislop.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/m
|
||||
| `antislop-copywriting` | Copy & text: headlines, CTAs, tone, fake stats, anti-AI-writing patterns, markdown hygiene | v2.3.0 |
|
||||
| `antislop-human` | Human: contrast (with the checker), keyboard, focus, states | v2.4.0 |
|
||||
| `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets, navigation | v2.5.0 |
|
||||
| `antislop-code` | Code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code | v3.1.0 |
|
||||
|
||||
Pick what matches the work: UI work → `antislop-ui`, copy work → `antislop-copywriting`, people work → `antislop-human`, mobile layout work → `antislop-layoutmobile`, more than one → install several, or none (the core alone is a complete filter).
|
||||
Pick what matches the work: UI work → `antislop-ui`, copy work → `antislop-copywriting`, people work → `antislop-human`, mobile layout work → `antislop-layoutmobile`, code comments work → `antislop-code`, more than one → install several, or none (the core alone is a complete filter).
|
||||
|
||||
## Usage Modes
|
||||
|
||||
@@ -82,7 +83,7 @@ antislop is used one of two ways, chosen at the start of a session:
|
||||
|
||||
## Roadmap
|
||||
|
||||
**v3.0.0 shipped**: antislop is packaged as installable skills. See [ROADMAP.md](ROADMAP.md). The skill plan that built toward it (one skill per version) is complete; `antislop-docs` and `antislop-identity` are candidates for after v3.
|
||||
**v3.0.0 shipped**: antislop is packaged as installable skills, then refined through v3.0.1 and v3.0.2. The next release, **v3.1.0**, ships the `antislop-code` skill. See [ROADMAP.md](ROADMAP.md) for the tracker, including the cross-agent plugin plan.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
||||
+12
-5
@@ -1,10 +1,10 @@
|
||||
# antislop: Roadmap to v3.0.0
|
||||
# antislop: Roadmap
|
||||
|
||||
> How antislop grows from a single rules file into an installable, cross-agent skill/plugin. New to antislop? Read the [guide](guide.md) first. See [README.md](README.md) for the product.
|
||||
|
||||
## Where we are
|
||||
|
||||
The latest release is **v3.0.0**. antislop is now a **packaged system**: a lean, always-loaded **core** plus four **skills**, each shipped as a standard agent skill folder (`skills/<name>/SKILL.md`):
|
||||
The latest release is **v3.0.2**. antislop is a **packaged system**: a lean, always-loaded **core** plus four **skills**, each shipped as a standard agent skill folder (`skills/<name>/SKILL.md`):
|
||||
|
||||
- `antislop`: the core rules filter (rules, tiers, Delivery Gate, liveliness)
|
||||
- `antislop-ui`: UI / visual
|
||||
@@ -12,7 +12,9 @@ The latest release is **v3.0.0**. antislop is now a **packaged system**: a lean,
|
||||
- `antislop-human`: human / accessibility, home of the contrast checker
|
||||
- `antislop-layoutmobile`: mobile / responsive
|
||||
|
||||
The system installs three ways from one repo: the interactive picker (`npx antislop-ai`), the skills directory (`npx skills add miqdadbadjuber/anti-slop`, listed on skills.sh), and the Claude Code plugin marketplace (`.claude-plugin/plugin.json`). The contrast checker is also exposed as an MCP tool inside the plugin.
|
||||
The next release, **v3.1.0**, ships a fifth skill: `antislop-code`, the code comment filter.
|
||||
|
||||
The system installs three ways from one repo: the interactive picker (`npx antislop-ai`), the skills directory (`npx skills add miqdadbadjuber/anti-slop`, listed on skills.sh), and the Claude Code plugin marketplace (`.claude-plugin/plugin.json`). The contrast checker is also exposed as an MCP tool inside the plugin. Each skill folder also carries a short `README.md` that says on GitHub what the skill is for.
|
||||
|
||||
The **First-Run Install Wizard** still lives inside `antislop.md` as the manual path. The single-file core remains a complete filter you can paste into any chat window.
|
||||
|
||||
@@ -26,7 +28,7 @@ v3.0.0 was reached by adding one concern per version, each as a separate **skill
|
||||
|
||||
That kept the filter pull-only-what-you-need and made the v3 packaging mechanical rather than a rewrite. Occasional +0.1 patches shipped something that is not a skill, like v2.4.1's plain-English `guide.md`; those did not change the skill plan.
|
||||
|
||||
### The skill plan (complete)
|
||||
### The skill plan
|
||||
|
||||
| Version | Skill | Concern |
|
||||
|---------|-------|---------|
|
||||
@@ -34,8 +36,9 @@ That kept the filter pull-only-what-you-need and made the v3 packaging mechanica
|
||||
| v2.3.0 | `antislop-copywriting` | Copy and text: headlines, CTAs, tone, fake stats, markdown hygiene |
|
||||
| v2.4.0 | `antislop-human` | Human: contrast, keyboard, focus, states (home of the contrast checker) |
|
||||
| v2.5.0 | `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets, navigation |
|
||||
| v3.1.0 | `antislop-code` | Code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code |
|
||||
|
||||
`antislop-docs` and `antislop-identity` are candidates for after v3, not part of the shipped plan.
|
||||
The plan to v3.0.0 is complete. `antislop-code` is the first skill added after v3. `antislop-docs` and `antislop-identity` remain candidates for later, not part of the shipped plan.
|
||||
|
||||
## v3.0.0: the skill/plugin
|
||||
|
||||
@@ -58,11 +61,15 @@ What v3.0.0 shipped:
|
||||
- [x] v2.4.2 - skill checklist polarity fix (#9) and docs cleanup, merged from PRs #8 and #10
|
||||
- [x] v2.5.0 - `antislop-layoutmobile` (breakpoints, scale, grids, overflow, tap targets, navigation)
|
||||
- [x] v3.0.0 - skill/plugin packaging: `skills/` folders, two doors, picker CLI, MCP contrast tool, MIT license
|
||||
- [x] v3.0.1 - Snyk W012 fix (no runtime curl in the packaged core), npm package author to antislop, docs clarity
|
||||
- [x] v3.0.2 - adaptive python (python3 on macOS/Linux, python on Windows), App & Dashboard + copy voice patterns, pointer fix
|
||||
- [ ] v3.1.0 - `antislop-code` skill, per-skill READMEs, Filler Data and Emoji as Decoration patterns
|
||||
|
||||
## After v3
|
||||
|
||||
- [ ] `antislop-docs` (skill candidate)
|
||||
- [ ] `antislop-identity` (skill candidate)
|
||||
- [ ] **Cross-agent plugin** (plan, no promised version): antislop installs as a plugin on more agents the way superpowers installs everywhere from one repo, with paths for Antigravity, Codex, Cursor, Gemini CLI, and others. Estimate: Q3-Q4 2026.
|
||||
|
||||
## Not in scope
|
||||
|
||||
|
||||
+5
-3
@@ -1,6 +1,6 @@
|
||||
# antislop
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules
|
||||
> Anti Slop: Rules for AI Coding Agents
|
||||
|
||||
> Follow these rules whenever generating or building UI for a website, web app, or any interface.
|
||||
> The goal: the design should feel **crafted by a designer**, not generated by AI.
|
||||
@@ -18,13 +18,14 @@ If no antislop pointer exists and this file is being read for the first time, ru
|
||||
|
||||
> If the user can use a terminal, the packaged install is better: run `npx antislop-ai` (interactive picker) or `npx skills add miqdadbadjuber/anti-slop`, then skip this section. The steps below are the manual fallback for chat-only setups.
|
||||
|
||||
1. **Declare the setup before doing anything.** Tell the user you will (a) download the skill(s) they choose into `skills/<name>/` subfolders next to this file, and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently.
|
||||
1. **Declare the setup before doing anything.** Tell the user you will (a) get the chosen skill(s) in place in `skills/<name>/` subfolders next to this file (the user fetches them; the agent never downloads from the network, see step 4), and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently.
|
||||
2. **Ask which skills to install** (multi-select, in the user's chat language). List only the skills that exist in this version of antislop:
|
||||
- **1. All** (recommended): install every available skill. Choose this when the work spans UI, copy, people, or mobile layout.
|
||||
- **2. `antislop-ui`** (UI / visual): pick this for building or editing a website, web app, or interface: color, layout, components, decoration, motion.
|
||||
- **3. `antislop-copywriting`** (copy & text): pick this for writing or editing copy: headlines, CTAs, value propositions, tone, landing-page text, product prose.
|
||||
- **4. `antislop-human`** (people): pick this for making sure a UI works for people with different eyes, hands, and setups: contrast, keyboard, focus, states.
|
||||
- **5. `antislop-layoutmobile`** (mobile / responsive): pick this for layouts that have to hold up on a phone: breakpoints, scale, grids, overflow, tap targets.
|
||||
- **6. `antislop-code`** (code comments): pick this for writing or editing code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code.
|
||||
- New skills appear here as they ship; never offer a skill that does not exist in this version.
|
||||
|
||||
If the user declines or says "core only", stop here and use this file alone as the filter. Do not install anything.
|
||||
@@ -37,11 +38,12 @@ If no antislop pointer exists and this file is being read for the first time, ru
|
||||
```md
|
||||
<!-- antislop:start -->
|
||||
## antislop
|
||||
For UI, copy, people, or mobile layout work, read `antislop.md` (core) and then the skill for the task:
|
||||
For UI, copy, people, mobile layout, or code comments work, read `antislop.md` (core) and then the skill for the task:
|
||||
- UI / visual: `skills/antislop-ui/SKILL.md`
|
||||
- Copy & text: `skills/antislop-copywriting/SKILL.md`
|
||||
- People: `skills/antislop-human/SKILL.md`
|
||||
- Mobile / responsive: `skills/antislop-layoutmobile/SKILL.md`
|
||||
- Code comments: `skills/antislop-code/SKILL.md`
|
||||
Before starting, ask the user when antislop applies: during the work, or after it is done.
|
||||
<!-- antislop:end -->
|
||||
```
|
||||
|
||||
+2
-1
@@ -17,6 +17,7 @@ const EXTRA_SKILLS = [
|
||||
{ value: 'antislop-copywriting', label: 'antislop-copywriting', hint: 'copywriting and text rules' },
|
||||
{ value: 'antislop-human', label: 'antislop-human', hint: 'accessibility, with the contrast checker' },
|
||||
{ value: 'antislop-layoutmobile', label: 'antislop-layoutmobile', hint: 'mobile layout rules' },
|
||||
{ value: 'antislop-code', label: 'antislop-code', hint: 'code comment rules' },
|
||||
]
|
||||
|
||||
function stop(message) {
|
||||
@@ -26,7 +27,7 @@ function stop(message) {
|
||||
|
||||
async function main() {
|
||||
if (process.argv.includes('--version') || process.argv.includes('-v')) {
|
||||
console.log('antislop 3.0.2')
|
||||
console.log('antislop 3.1.0')
|
||||
return
|
||||
}
|
||||
|
||||
|
||||
+2
-2
@@ -14,8 +14,8 @@ export function banner() {
|
||||
'',
|
||||
...LOGO,
|
||||
'',
|
||||
' ' + pc.dim('Anti AI Slop: Design & Copy Rules'),
|
||||
' ' + pc.dim('installer v3.0.2'),
|
||||
' ' + pc.dim('Anti Slop: Rules for AI Coding Agents'),
|
||||
' ' + pc.dim('installer v3.1.0'),
|
||||
'',
|
||||
].join('\n')
|
||||
}
|
||||
|
||||
+2
-1
@@ -87,6 +87,7 @@ const SKILL_LINES = {
|
||||
'antislop-copywriting': 'Copy & text: `antislop-copywriting`',
|
||||
'antislop-human': 'People: `antislop-human`',
|
||||
'antislop-layoutmobile': 'Mobile / responsive: `antislop-layoutmobile`',
|
||||
'antislop-code': 'Code comments: `antislop-code`',
|
||||
}
|
||||
|
||||
// Names the skills instead of importing the core. The skills sit in the agent's
|
||||
@@ -96,7 +97,7 @@ function pointerBlock(skills) {
|
||||
return [
|
||||
POINTER_START,
|
||||
'## antislop',
|
||||
'For UI, copy, people, or mobile layout work, load the antislop skill for the task:',
|
||||
'For UI, copy, people, mobile layout, or code comments work, load the antislop skill for the task:',
|
||||
...skills.filter((s) => SKILL_LINES[s]).map((s) => `- ${SKILL_LINES[s]}`),
|
||||
'Before starting, ask the user when antislop applies: during the work, or after it is done.',
|
||||
POINTER_END,
|
||||
|
||||
Generated
+2
-2
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "antislop-ai",
|
||||
"version": "3.0.2",
|
||||
"version": "3.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "antislop-ai",
|
||||
"version": "3.0.2",
|
||||
"version": "3.1.0",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"@clack/prompts": "^1.7.0",
|
||||
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "antislop-ai",
|
||||
"version": "3.0.2",
|
||||
"description": "Interactive installer for the antislop skills. Anti AI Slop: Design & Copy Rules.",
|
||||
"version": "3.1.0",
|
||||
"description": "Interactive installer for the antislop skills. Anti Slop: Rules for AI Coding Agents.",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"antislop-ai": "index.mjs"
|
||||
|
||||
@@ -10,7 +10,7 @@ const cliSkills = path.join(__dirname, '..', 'skills')
|
||||
const CORE_FRONTMATTER = [
|
||||
'---',
|
||||
'name: antislop',
|
||||
'description: "Anti AI Slop: Design & Copy Rules. The core rules filter for AI coding agents. Load always to stop generic AI slop."',
|
||||
'description: "Anti Slop: Rules for AI Coding Agents. The core filter. Load always to stop generic AI slop."',
|
||||
'allowed-tools: Read Write Edit Glob Grep',
|
||||
'---',
|
||||
'',
|
||||
|
||||
@@ -19,6 +19,7 @@ antislop is not only for building pages. Any AI output that can get sloppy benef
|
||||
- Build a new page or app: layout, color, parts of the page, animation, structure.
|
||||
- Write or rewrite copy: headlines, buttons, emails, and tone that do not sound AI-made.
|
||||
- Keep the page usable by people: readable colors, keyboard use, clear focus, and button states.
|
||||
- Clean up code comments: remove the generic AI ones, keep the ones that matter.
|
||||
- Check work you already have: it can list what to fix.
|
||||
|
||||
The main file (the core) covers all of it. Skills (see What is a skill?) go deeper into one concern when you want more.
|
||||
@@ -49,8 +50,9 @@ A skill is an optional folder (with a `SKILL.md` inside) that goes deeper into o
|
||||
- `antislop-copywriting`: the text. Headlines, buttons, tone, made-up statistics.
|
||||
- `antislop-human`: the people. Readable colors, keyboard use, clear focus, and button states.
|
||||
- `antislop-layoutmobile`: the small screen. Layout that reflows on a phone, tap targets, navigation.
|
||||
- `antislop-code`: the comments in your code. Remove the generic AI ones, keep the ones that carry information.
|
||||
|
||||
Pick the one that matches your work. UI work means `antislop-ui`. Copy work means `antislop-copywriting`. People work means `antislop-human`. Mobile layout work means `antislop-layoutmobile`. More than one? Ask for "All". None? The core alone is enough.
|
||||
Pick the one that matches your work. UI work means `antislop-ui`. Copy work means `antislop-copywriting`. People work means `antislop-human`. Mobile layout work means `antislop-layoutmobile`. Code comments work means `antislop-code`. More than one? Ask for "All". None? The core alone is enough.
|
||||
|
||||
## How to install
|
||||
|
||||
@@ -118,7 +120,7 @@ The main file holds everything: the rules and the wizard. Skills are optional de
|
||||
|
||||
## Where is this going?
|
||||
|
||||
The skill plan is complete. antislop v3.0.0 is now packaged: installable as skills, installable as a plugin, and still available as one file. See the roadmap, the page that lists what is coming next, [here](ROADMAP.md).
|
||||
antislop is packaged: installable as skills, installable as a plugin, and still available as one file. Skills keep shipping as they are ready; the next one is `antislop-code`. See the roadmap, the page that lists what is coming next, [here](ROADMAP.md).
|
||||
|
||||
## Feedback
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# antislop-code
|
||||
|
||||
Code comment rules for generated code. When your AI tool writes or edits code comments, this skill removes the ones that read as generic AI (decorative separators, restating the obvious, step-by-step narration) and keeps the ones that carry real information. Part of the antislop system.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not about banning comments, and it never rewrites your code. It only removes comments that read as generic AI and keeps the ones that matter. The code stays exactly as it is.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder.
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: antislop-code
|
||||
description: "Code comment hygiene for AI coding agents: remove generic AI-slop comments, keep the valuable ones, never touch the code."
|
||||
allowed-tools: Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop-code
|
||||
|
||||
> Anti Slop: Rules for AI Coding Agents. Code Comments skill
|
||||
|
||||
> Part of the antislop system. Read together with `antislop.md` (the core). This skill filters comments that read as generically AI (decorative, restating the obvious, stiff, loud) while preserving the comments that carry real information. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits code comments.
|
||||
|
||||
## How to use this skill
|
||||
|
||||
- Load together with `antislop.md` whenever the task touches code comments. The core holds the mechanism (the purpose test, the three tiers, the Delivery Gate); this skill holds comment-specific depth.
|
||||
- Every entry has the same shape: **Tell** (the pattern), **Why** (why it reads as slop), **Fix** (what to do instead), with the governing core rule cited as R-XX.
|
||||
- **Scope guardrail:** this skill only modifies comments. Never modify executable code, identifiers, imports, formatting, indentation, whitespace, control flow, or logic. When in doubt, leave the code untouched.
|
||||
- The Delivery Gate in the core remains the gate. The "Code Comment Checklist" at the end of this file is the comment-specific supplement to run alongside it.
|
||||
|
||||
## Comments That Add Nothing
|
||||
|
||||
### Decorative Separators
|
||||
|
||||
- **Tell:** banner comments built from repeated characters, ALL CAPS labels, or box drawing around a section name: `// =======================` around `Authentication`, `// -------- WORKFLOW --------`, or a `/* ---- ROUTES ---- */` header.
|
||||
- **Why:** the decoration is the message. A label wrapped in `=` or `-` signals "AI made this" without adding information, and ALL CAPS reads as shouting.
|
||||
- **Fix:** replace with a single plain line, or remove entirely if the label adds nothing (R-31).
|
||||
|
||||
### Restating the Obvious
|
||||
|
||||
- **Tell:** a comment that repeats what the next line or declaration already shows, like `// Initialize the variable` above `let count = 0`, `// User class` above `class User {}`, `// Validate user` above `function validateUser()`, or `const userAge = 25; // User age is 25`.
|
||||
- **Why:** it doubles the reading load without adding anything. The code already says it; the comment just repeats it.
|
||||
- **Fix:** remove and leave the line of code alone.
|
||||
|
||||
### Workflow Narration
|
||||
|
||||
- **Tell:** comments that narrate the flow step by step, like `// Step 1: Validate input`, `// Step 2: Process request`, `// Step 3: Return response`, or `// First...`, `// Next...`, `// Finally...`.
|
||||
- **Why:** the control flow is visible in the code itself. Numbering it reads as a checklist, not an explanation.
|
||||
- **Fix:** remove. If the flow is genuinely hard to follow, that is a structure problem, not a missing comment problem.
|
||||
|
||||
### Empty Labels
|
||||
|
||||
- **Tell:** generic labels with no information behind them: `// Main logic`, `// Core logic`, `// Business logic`, `// Helper function`, `// Entry point`, `// Error handling`, or `// Note: This is important.` / `// Important: Please read.`
|
||||
- **Why:** the label names a category, not a fact. "Main logic" tells the reader nothing they could not infer from the code.
|
||||
- **Fix:** remove unless the label carries specific information. "Note: retries happen only on 5xx" earns its place; "Note: this is important" does not.
|
||||
|
||||
### Vague Placeholders
|
||||
|
||||
- **Tell:** comments that promise future work without saying what: `// TODO: Improve this`, `// Future improvements`, `// Additional optimization can be added here`, `// Add more validation`.
|
||||
- **Why:** a vague TODO is noise. It names a feeling (this could be better) instead of a task (what, and why).
|
||||
- **Fix:** remove. Keep a TODO only when it names a specific task with enough context to act on.
|
||||
|
||||
### Signature Echo
|
||||
|
||||
- **Tell:** documentation that only restates the signature, like a JSDoc block that repeats `@param price The price.` and `@returns Total price.` for a function whose name and parameters already say all of it.
|
||||
- **Why:** docs that echo the signature add length, not understanding. The reader learns nothing new.
|
||||
- **Fix:** simplify or remove the echo. Keep documentation that explains business rules, edge cases, assumptions, algorithms, limitations, side effects, API behavior, or security implications. Never strip real documentation.
|
||||
|
||||
### Decorative Emoji
|
||||
|
||||
- **Tell:** emoji used as decoration in comments, like `// ✅ Validation` or `// 🚀 Performance`.
|
||||
- **Why:** emoji is visual noise in code, and the specific set (✅, 🚀, 🔒) is the AI default vocabulary.
|
||||
- **Fix:** replace with plain English, or remove if the label adds nothing.
|
||||
|
||||
### End Markers
|
||||
|
||||
- **Tell:** comments that only mark the end of a block, like `} // end if`, `# End of function`, or `// End processOrder`.
|
||||
- **Why:** the closing brace already ends the block. The marker exists out of habit, not need.
|
||||
- **Fix:** remove. In the rare case an end marker genuinely helps a long file, keep it only where it prevents confusion, not as a habit.
|
||||
|
||||
## How It Should Read
|
||||
|
||||
### Line-by-Line Narration
|
||||
|
||||
- **Tell:** a comment on every trivial statement, narrating each line as it is written: `// Initialize count`, then `// Loop items`, then `// Get item`, then `// Increment`, then `// Return result`.
|
||||
- **Why:** when every line is commented, none of the comments matter. The reader has to check each one to find the one that carries meaning.
|
||||
- **Fix:** write one concise comment per logical block instead of one per line. If the block needs no comment, write none.
|
||||
|
||||
### Stiff or Loud Wording
|
||||
|
||||
- **Tell:** comments that sound formal, long, or shout: "This function is responsible for validating whether the supplied credentials are valid before continuing with the authentication process", or `// MAIN LOGIC` in caps.
|
||||
- **Why:** formal and loud wording reads as generated, not as an engineer leaving a note for the next person.
|
||||
- **Fix:** write short, sentence-case lines in a natural developer voice: `// Validate credentials before issuing a token.` Good comments explain why, not what, and they stay short.
|
||||
|
||||
## Not a Ban (preserve these)
|
||||
|
||||
Never remove comments that explain:
|
||||
|
||||
- business logic and intent
|
||||
- architectural decisions
|
||||
- security considerations
|
||||
- performance trade-offs
|
||||
- concurrency behavior
|
||||
- protocol details
|
||||
- API contracts
|
||||
- workarounds
|
||||
- edge cases and assumptions
|
||||
- licensing and legal notices
|
||||
|
||||
Example that must stay:
|
||||
|
||||
```js
|
||||
// Stripe may retry webhook deliveries for up to three days.
|
||||
// Ignore duplicate events using the event ID.
|
||||
```
|
||||
|
||||
A comment earns its place when it explains something the code does not already show: the reason, the constraint, the non-obvious behavior.
|
||||
|
||||
## Code Comment Checklist
|
||||
|
||||
Run these alongside the core Delivery Gate when the task touches comments. All answers must be **yes**:
|
||||
|
||||
- [ ] Does every comment add information the code does not already show? (R-31)
|
||||
- [ ] Do the comments avoid decorative separators, ALL CAPS banners, and box-drawn headers?
|
||||
- [ ] Do the comments avoid restating the obvious line, declaration, or signature?
|
||||
- [ ] Do the comments avoid step-by-step workflow narration?
|
||||
- [ ] Do the comments avoid empty labels and vague TODOs that name no task?
|
||||
- [ ] Do the comments avoid decorative emoji and end markers?
|
||||
- [ ] Is the comment density one per logical block, not one per line?
|
||||
- [ ] Do the remaining comments read short, natural, and in sentence case?
|
||||
- [ ] Is the scope guardrail held: only comments changed, the code untouched?
|
||||
@@ -0,0 +1,11 @@
|
||||
# antislop-copywriting
|
||||
|
||||
Copy and text rules for generated prose. When your AI tool writes headlines, landing pages, or product copy, this skill checks the text for the patterns that give AI-written prose away and fixes them. Part of the antislop system.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not a thesaurus, and not a tone guide that makes your text fancier. It only removes the patterns that make AI-written prose easy to spot. The voice and the actual wording stay yours.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder.
|
||||
@@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop-copywriting
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules. Copy & Text skill
|
||||
> Anti Slop: Rules for AI Coding Agents. Copy & Text skill
|
||||
|
||||
> Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the copy and text concern: headlines, CTAs, tone, value propositions, and the patterns that make AI-written prose easy to spot. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits marketing copy, product copy, landing-page text, or any prose meant for people to read.
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# antislop-human
|
||||
|
||||
Human and accessibility rules for generated UI. When your AI tool builds an interface, this skill checks that real people with different eyes, hands, and setups can use it: contrast, keyboard, focus, and states. Part of the antislop system.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not a replacement for real accessibility testing, and not a style pass. It keeps the UI usable by people. A human check still runs last.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder.
|
||||
@@ -5,7 +5,7 @@ allowed-tools: Bash(python *) Bash(python3 *) Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop-human
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules. Human skill
|
||||
> Anti Slop: Rules for AI Coding Agents. Human skill
|
||||
|
||||
> Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the human concern: the UI must stay usable by people with different eyes, hands, and setups. Contrast, keyboard, focus, states, and the mobile details that exclude people.
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ import sys
|
||||
|
||||
PROTOCOL_VERSION = "2024-11-05"
|
||||
SERVER_NAME = "antislop-contrast"
|
||||
SERVER_VERSION = "3.0.2"
|
||||
SERVER_VERSION = "3.1.0"
|
||||
|
||||
TOOLS = [
|
||||
{
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# antislop-layoutmobile
|
||||
|
||||
Mobile layout rules for generated interfaces. When your AI tool builds a layout, this skill checks that it still holds up on a small screen: breakpoints, grids, overflow, tap targets, and navigation. Part of the antislop system.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not a responsive framework, and it will not write your CSS. It checks that a layout holds up on a phone and fixes what breaks. The layout structure stays yours.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder.
|
||||
@@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop-layoutmobile
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules. Mobile Layout skill
|
||||
> Anti Slop: Rules for AI Coding Agents. Mobile Layout skill
|
||||
|
||||
> Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the mobile layout concern: how a layout must reflow on small screens. Breakpoints, scale, grids, overflow, tap targets, and navigation. It references core rules by number and never duplicates or renumbers them. Load it when the task builds or edits a layout that has to hold up on a phone.
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# antislop-ui
|
||||
|
||||
UI and visual rules for generated interfaces. When your AI tool builds or edits a website, app, or dashboard, this skill checks the result for the patterns that give AI-generated work away (decorative emoji, filler data like "John Doe", generic AI icons) and fixes them. Part of the antislop system.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not a design system, and not a way to make your design prettier or more modern. It only filters the slop. The visual taste and the actual design stay with you.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder.
|
||||
@@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop-ui
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules. UI & Visual skill
|
||||
> Anti Slop: Rules for AI Coding Agents. UI & Visual skill
|
||||
|
||||
> Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the UI/visual concern: color, layout, components, decoration, structural flow, and motion. It references core rules by number and never duplicates or renumbers them. Load it when the task builds or edits a website, web app, or any interface.
|
||||
|
||||
@@ -135,6 +135,12 @@ allowed-tools: Read Write Edit Glob Grep
|
||||
- **Why:** these glyphs are the generic vocabulary of "AI product". They communicate nothing about the specific feature.
|
||||
- **Fix:** use icons genuinely relevant to the content, with the relevance written down when the glyph is generic (R-04). If no appropriate icon exists, use none. The feature label does the work.
|
||||
|
||||
### Emoji as Decoration
|
||||
|
||||
- **Tell:** literal emoji scattered through the copy, headings, badges, and buttons: 🚀 in a headline, ✅ beside every feature bullet, 🔥 on a CTA, 📈 above a chart title.
|
||||
- **Why:** emoji is the loudest shorthand for "this was generated, not written". In a UI it competes with the content for attention and flattens the product's voice into the same cheerful default as every other AI site.
|
||||
- **Fix:** remove emoji from UI text. If a concept needs a mark, use a real, relevant icon with the reason written down (R-04), or no mark at all. The copy carries the meaning; the emoji adds nothing.
|
||||
|
||||
### Small Arrows on Every Button
|
||||
|
||||
- **Tell:** `→` or `↗` placed on almost every button as pure decoration.
|
||||
@@ -213,6 +219,12 @@ The patterns above are landing-page shapes. These are the app-side equivalents:
|
||||
- **Why:** the columns come from the table component, not from the data. The user scans for the field that decides their next move and it is not there.
|
||||
- **Fix:** pick columns from the decision the user makes in this table, and put the deciding field early. The row menu holds actions that exist; anything that does nothing comes out (R-26).
|
||||
|
||||
### Filler Data in Fields and Columns
|
||||
|
||||
- **Tell:** empty form fields and table columns filled with fake but plausible data: `John Doe`, `johndoe@example.com`, `"Let's build something"`, phone numbers and dates that belong to nobody.
|
||||
- **Why:** fabricated content disguised as real. It reads fine in a mockup and falls apart the moment a real user looks: the name is not a customer, the email is not a lead, and the message is a tagline. It is the strongest tell that the screen was generated, not built.
|
||||
- **Fix:** leave empty cells empty, or use placeholders that clearly say what goes there: `Your Name`, `email@example.com`, `Drop your message here...`, or `[REAL DATA]` when a value is expected (R-23, R-38). Real data goes in when it exists. Generic filler copy like "Let's build something" is buzzword slop and does not belong in a data column (R-16).
|
||||
|
||||
### Placeholder Empty and Loading States
|
||||
|
||||
- **Tell:** "No data available" with an illustration, a bare spinner, or a full-page skeleton that mimics a layout the real data never fills.
|
||||
@@ -239,11 +251,13 @@ Run these alongside the core Delivery Gate when the task is UI work. All answers
|
||||
|
||||
- [ ] Is the palette derived from `DESIGN.md` or a written brand identity, not the default gradient set? (R-01, R-29)
|
||||
- [ ] Is the accent used at the key moment only, not spread across every element? (core Part 3, one deliberate accent)
|
||||
- [ ] Is the copy free of decorative emoji scattered through headings, bullets, and buttons? (R-04)
|
||||
- [ ] Do section compositions vary according to the declared RHYTHM dial instead of repeating one template? (R-05)
|
||||
- [ ] Does every navigation item and interactive element have a real destination or behavior, or a visible "Coming soon" label? (R-24, R-26)
|
||||
- [ ] Does motion follow the declared MOTION dial and serve a written purpose, with no endless loops? (R-19)
|
||||
- [ ] Is glass, glow, shadow, and radius used at their dose caps, not as a page-wide default? (R-10, R-11, R-12, R-13)
|
||||
- [ ] On an app screen, is the layout built around the decision the user makes there, rather than the sidebar plus stat row plus chart plus table default? (C-3, R-20)
|
||||
- [ ] Is every number, delta, feed entry, and table row real or a labelled placeholder, with no invented metrics? (R-17, R-18, R-38)
|
||||
- [ ] Do empty form fields and table cells stay empty or carry honest placeholders (Your Name, email@example.com) instead of fake-looking data (John Doe, johndoe@example.com)? (R-23, R-38)
|
||||
- [ ] Do the empty, loading, and error states name the cause and the next action instead of saying "No data"? (R-27)
|
||||
- [ ] Does the page hold up at every breakpoint, theme, and state, and pass keyboard-only use? (R-03, R-34, C-4)
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# antislop
|
||||
|
||||
The core. Anti Slop: Rules for AI Coding Agents. A filter that stops generated UI and copy from reading as generic "AI slop". It is a filter, not a style guide: no prescribed colors, fonts, or layouts.
|
||||
|
||||
## What it is
|
||||
|
||||
The core rules always load. They have mandatory rules in three tiers, a Liveliness Toolkit, and a Delivery Gate that checks the work before it ships. The core works alone or with the deeper skills next to it (ui, copywriting, human, layoutmobile, code), one per concern.
|
||||
|
||||
## What it is not
|
||||
|
||||
Not a style guide and not a design system. It does not pick colors, fonts, or layouts, and it never beautifies on its own. Direction comes from you and your DESIGN.md.
|
||||
|
||||
## Where the rules live
|
||||
|
||||
The source is `antislop.md` at the repo root. `SKILL.md` in this folder is the same rules packaged as a skill so your AI agent can load it directly.
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: antislop
|
||||
description: "Anti AI Slop: Design & Copy Rules. The core rules filter for AI coding agents. Load always to stop generic AI slop."
|
||||
description: "Anti Slop: Rules for AI Coding Agents. The core filter. Load always to stop generic AI slop."
|
||||
allowed-tools: Read Write Edit Glob Grep
|
||||
---
|
||||
# antislop
|
||||
|
||||
> Anti AI Slop: Design & Copy Rules
|
||||
> Anti Slop: Rules for AI Coding Agents
|
||||
|
||||
> Follow these rules whenever generating or building UI for a website, web app, or any interface.
|
||||
> The goal: the design should feel **crafted by a designer**, not generated by AI.
|
||||
@@ -23,13 +23,14 @@ If no antislop pointer exists and this file is being read for the first time, ru
|
||||
|
||||
> If the user can use a terminal, the packaged install is better: run `npx antislop-ai` (interactive picker) or `npx skills add miqdadbadjuber/anti-slop`, then skip this section. The steps below are the manual fallback for chat-only setups.
|
||||
|
||||
1. **Declare the setup before doing anything.** Tell the user you will (a) download the skill(s) they choose into `skills/<name>/` subfolders next to this file, and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently.
|
||||
1. **Declare the setup before doing anything.** Tell the user you will (a) get the chosen skill(s) in place in `skills/<name>/` subfolders next to this file (the user fetches them; the agent never downloads from the network, see step 4), and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently.
|
||||
2. **Ask which skills to install** (multi-select, in the user's chat language). List only the skills that exist in this version of antislop:
|
||||
- **1. All** (recommended): install every available skill. Choose this when the work spans UI, copy, people, or mobile layout.
|
||||
- **2. `antislop-ui`** (UI / visual): pick this for building or editing a website, web app, or interface: color, layout, components, decoration, motion.
|
||||
- **3. `antislop-copywriting`** (copy & text): pick this for writing or editing copy: headlines, CTAs, value propositions, tone, landing-page text, product prose.
|
||||
- **4. `antislop-human`** (people): pick this for making sure a UI works for people with different eyes, hands, and setups: contrast, keyboard, focus, states.
|
||||
- **5. `antislop-layoutmobile`** (mobile / responsive): pick this for layouts that have to hold up on a phone: breakpoints, scale, grids, overflow, tap targets.
|
||||
- **6. `antislop-code`** (code comments): pick this for writing or editing code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code.
|
||||
- New skills appear here as they ship; never offer a skill that does not exist in this version.
|
||||
|
||||
If the user declines or says "core only", stop here and use this file alone as the filter. Do not install anything.
|
||||
@@ -42,11 +43,12 @@ If no antislop pointer exists and this file is being read for the first time, ru
|
||||
```md
|
||||
<!-- antislop:start -->
|
||||
## antislop
|
||||
For UI, copy, people, or mobile layout work, read `antislop.md` (core) and then the skill for the task:
|
||||
For UI, copy, people, mobile layout, or code comments work, read `antislop.md` (core) and then the skill for the task:
|
||||
- UI / visual: `skills/antislop-ui/SKILL.md`
|
||||
- Copy & text: `skills/antislop-copywriting/SKILL.md`
|
||||
- People: `skills/antislop-human/SKILL.md`
|
||||
- Mobile / responsive: `skills/antislop-layoutmobile/SKILL.md`
|
||||
- Code comments: `skills/antislop-code/SKILL.md`
|
||||
Before starting, ask the user when antislop applies: during the work, or after it is done.
|
||||
<!-- antislop:end -->
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user