agentleFS
lukesw55lukesw55/ai-pm-toolkit/.agents/skills/anti-slop/SKILL.md

anti-slop

Skill1 starsChanged 42 days agoMITView on GitHub

Detect and remove AI slop from agent outputs before they reach the repo or the user. Use before writing or editing code, comments, docstrings, markdown docs, README sections, PR descriptions, Jira/Linear tickets, ADRs, plans, or chat replies longer than two sentences. Also use when reviewing diffs, PRs, generated files, or anything the user calls "AI-generated", "slop", "too verbose", "boilerplate", "generic", "ChatGPT-ish", "Claude-ish", "com cara de IA", "tá com slop", or "tira o ruído". Pairs with humanizer for prose and Stop hooks for runtime enforcement.

33 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use handoff and research.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 4 projects that use this

  • NVIDIASkill

    research

    Before designing a feature, research how comparable libraries solve the problem, check best practices, known pitfalls, and upstream changes. Use when starting a new feature, investigating an unfamiliar area, or the user asks to research something.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. 0 are common, 29 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 32 edited versions we read keep these.

  • 29

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Remove AI tells from code, comments, docs, repo structure, PR text, and agent replies.

    line 8
  2. Distinctive:

    Delete generic structure instead of polishing it.

    line 20
  3. Distinctive:

    Do not create files the user did not ask for.

    line 21
  4. Distinctive:

    Do not narrate obvious tool use.

    line 22
  5. Distinctive:

    Do not add abstractions for hypothetical reuse.

    line 23
  6. Distinctive:

    If removing "AI slop" removes evidence, behavior, constraints, or useful context, you removed too much.

    line 26
  7. Distinctive:

    Use when creating new output.

    line 67
  8. Distinctive:

    Before final output, ask internally:

    line 71
  9. Distinctive:

    Use when reviewing existing material.

    line 79
  10. Distinctive:

    Do not rewrite the whole file unless the user asked.

    line 97
  11. Distinctive:

    Use when reviewing code changes.

    line 101
  12. Distinctive:

    Run this scan against any output before sending it — diff, doc, reply, test file.

    line 126
  13. Distinctive:

    If the scan flags three or more boxes, the output is shaped wrong.

    line 162
  14. Distinctive:

    Never create these unless the user explicitly asks:

    line 166
  15. Distinctive:

    Do not create ADRs for reversible implementation details.

    line 178
  16. Distinctive:

    Do not add README sections such as Contributing, Roadmap, License, Code of Conduct, Architecture, or Table of Contents unless the repo …

    line 180
  17. Distinctive:

    Check existing style before adding new patterns.

    line 189
  18. Distinctive:

    Prefer deletion over abstraction.

    line 190
  19. Distinctive:

    Prefer direct code over wrappers.

    line 191
  20. Distinctive:

    Prefer existing tests over new scaffolding.

    line 192
  21. Distinctive:

    Avoid opportunistic cleanup outside the requested scope.

    line 197
  22. Distinctive:

    Do not introduce new dependencies for formatting or convenience.

    line 198
  23. Distinctive:

    Do not create helper files unless required by the requested change.

    line 199
  24. Distinctive:

    Remove any code that exists only because an AI would "be safe".

    line 205
  25. Distinctive:

    Remove comments that explain obvious code.

    line 206
  26. Distinctive:

    Remove generic docs, summaries, and headings.

    line 207
  27. Distinctive:

    Verify the change still preserves the user's requested behavior.

    line 208
  28. Distinctive:

    Use this checklist internally:

    line 212
  29. Very specific:

    When a single artefact mixes prose and structure (PRD, ADR, exec memo): run anti-slop first for the structural pass, then humanizer for the …

    line 283
  30. Distinctive:

    If multiple skills apply, run the specific skill first, then anti-slop as the final structural gate.

    line 287

“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Anti-slop

Remove AI tells from code, comments, docs, repo structure, PR text, and agent replies.

This skill is a gate, not a writing style guide. Use it before producing or modifying anything that might enter the codebase or a developer workflow.

Progressive loading

Load this SKILL.md first. For large or specialized tasks, use references/progressive-loading.md to choose the narrowest supporting reference before reading more.

Non-negotiables

  1. Ship the smallest useful change.
  2. Trust internal contracts unless a boundary is involved.
  3. Delete generic structure instead of polishing it.
  4. Do not create files the user did not ask for.
  5. Do not narrate obvious tool use.
  6. Do not add abstractions for hypothetical reuse.
  7. Preserve substance while removing slop.

If removing "AI slop" removes evidence, behavior, constraints, or useful context, you removed too much.

When to invoke

Invoke before:

  • writing or editing code
  • adding comments or docstrings
  • creating or expanding markdown docs
  • drafting README, PR, ADR, issue, ticket, changelog, or migration text
  • reviewing a diff or generated file
  • responding with more than two sentences and any structured format
  • creating any new file that was not explicitly requested
  • adding defensive checks, helper functions, interfaces, wrappers, logs, or config

Invoke when the user says:

  • remove AI slop
  • kill the slop
  • clean this up
  • less verbose
  • make it leaner
  • this looks AI-generated
  • review for AI tells
  • corta o boilerplate
  • tira o ruído
  • tá com cara de ChatGPT
  • esse código tá com slop
  • essa resposta tá com cara de IA

Skip only when:

  • returning raw logs, JSON, CSV, terminal output, or machine-readable data
  • answering with one factual sentence
  • making a tiny mechanical edit the user already specified exactly
  • the user explicitly asks for a verbose, template-heavy, or defensive style

Operating modes

1. Gate mode

Use when creating new output.

Apply the catalogue silently. The user should only see the lean result.

Before final output, ask internally:

What still makes this look AI-generated?

Then remove that tell unless it is load-bearing.

2. Sweep mode

Use when reviewing existing material.

Return:

## Findings
- path:line — TAG short issue

## Rewrites
```diff
...
```

## Remaining smell

One sentence naming what still feels AI-generated, or `None`.

Do not rewrite the whole file unless the user asked.

3. Diff mode

Use when reviewing code changes.

Prioritize comments that change behavior, reduce risk, or delete needless code. Avoid taste-only comments unless the slop is obvious.

Format:

- `path:line` — TAG issue. Suggested change: ...

Catalogues

The slop patterns themselves live in four references — load only the one that matches what you're about to write or review. Each reference is independent; skip the others.

When you're about to...Load
Write or review code, comments, types, identifiersreferences/code-catalogue.md — A1–A10
Write or review markdown docs, READMEs, PR/ADR/ticket bodiesreferences/doc-catalogue.md — B1–B12
Write a chat reply longer than two sentencesreferences/reply-catalogue.md — C1–C10
Write or review test files (unit / integration / E2E / fixtures)references/test-catalogue.md — E1–E8

Some patterns are hard-blocked by hooks/anti-slop-gate.sh (PreToolUse on Write/Edit/NotebookEdit) and hooks/scope-bloat-gate.sh (Stop): forbidden file basenames (see File artifact rules below), banner ===== lines (A10), decorative emoji headings (B6), and reply-shape signals (em-dash density, label-colon runs of 4+, headings on short prompts, dual-question close, response >5× prompt length without a doc keyword). To intentionally allow flagged content, use hooks/anti-slop-mark.sh "<final content>" to write a per-content sha256 sentinel. Everything else applies by hand.

30-second pre-output scan

Run this scan against any output before sending it — diff, doc, reply, test file. It catches the highest-frequency slop in under thirty seconds; anything that survives goes to the per-domain catalogue.

Code & tests
  [ ] Defensive check at an internal boundary?          → A1, delete
  [ ] try/except without real recovery?                  → A2, let it throw
  [ ] Single-use helper / constant / interface?          → A3 / A9, inline
  [ ] Generic identifier (data/result/helper/manager)?   → A4, name the domain
  [ ] Comment restating code below it?                   → A5, delete
  [ ] Log line narrating the function?                   → A6, delete
  [ ] Verbose test name "should ... when ..."?           → E1, shorten
  [ ] AAA comments in a short test?                      → E8, delete

Docs & artefacts
  [ ] Template-shaped heading (Overview/Details/...)?    → B1, name what changed
  [ ] Label-colon bullets with no evidence?              → B3, replace with facts
  [ ] Forced symmetry (3 pros / 3 cons / 3 risks)?       → B4, keep the real count
  [ ] Static metadata block (Status / Owner / Date)?     → B5, delete
  [ ] Decorative emoji heading?                          → B6, delete (also hook-blocked)
  [ ] TOC / glossary / "About this doc" on short doc?    → B7-B12, delete
  [ ] About to create PLAN.md / NOTES.md / SUMMARY.md?   → file-artifact rule, do not create
  [ ] Banner line of '=' or '-' (5+)?                    → A10, delete (also hook-blocked)

Replies
  [ ] Restating the prompt before answering?             → C1, answer directly
  [ ] Narrating tool calls before making them?           → C2, just call
  [ ] Sycophantic opener (Great question / Of course)?   → C3, start with the answer
  [ ] Trailing ## Summary / "Here's what I did"?         → C4 / C9, end at substance
  [ ] "Want me to also X, Y, Z?" follow-up spam?         → C5, stop
  [ ] Heading / bullets in a < 6-sentence answer?        → C6, inline
  [ ] Apologetic opener ("Sorry for the confusion")?     → C7, deliver the fix
  [ ] "Hope this helps! Let me know..."?                 → C8, delete
  [ ] Mid-reply "actually wait, let me reconsider..."?   → C10, edit silently
  [ ] Em-dash density obviously high?                    → hook-blocked, fix anyway

If the scan flags three or more boxes, the output is shaped wrong. Stop and rewrite — don't paper over slop with one or two edits.

File artifact rules

Never create these unless the user explicitly asks:

PLAN.md
NOTES.md
IMPLEMENTATION.md
SUMMARY.md
CHANGES.md
ANALYSIS.md
TODO.md

Do not create ADRs for reversible implementation details.

Do not add README sections such as Contributing, Roadmap, License, Code of Conduct, Architecture, or Table of Contents unless the repo actually needs them.

The right place for a change explanation is usually the PR body or commit message, not a parallel markdown file.

Agent workflow

Before editing:

  1. Identify the smallest file set needed.
  2. Check existing style before adding new patterns.
  3. Prefer deletion over abstraction.
  4. Prefer direct code over wrappers.
  5. Prefer existing tests over new scaffolding.

During editing:

  1. Avoid broad rewrites.
  2. Avoid opportunistic cleanup outside the requested scope.
  3. Do not introduce new dependencies for formatting or convenience.
  4. Do not create helper files unless required by the requested change.
  5. Keep names domain-specific.

After editing:

  1. Re-read the diff.
  2. Remove any code that exists only because an AI would "be safe".
  3. Remove comments that explain obvious code.
  4. Remove generic docs, summaries, and headings.
  5. Verify the change still preserves the user's requested behavior.

Review checklist

Use this checklist internally:

[ ] Did I add a guard for something an internal contract already guarantees?
[ ] Did I catch an exception without real recovery?
[ ] Did I create a helper, class, interface, constant, or config with one use?
[ ] Did I add a comment that restates code?
[ ] Did I use generic names like data/result/helper/manager?
[ ] Did I add logs that narrate execution?
[ ] Did I create a doc/file the user did not request?
[ ] Did I add headings, bullets, or symmetry because the output looked nicer?
[ ] Did I end with a summary or follow-up offer the user does not need?
[ ] Did I remove substance while removing slop?

Output contracts

When asked to clean existing material

Return only:

## Findings
- `path:line` — TAG issue

## Rewrites
```diff
...
```

## Remaining smell

None.

When asked to write new material

Return the clean artifact only. Do not explain that anti-slop was applied.

When asked to review a PR or diff

Return concise review comments. Prefer:

- `src/foo.ts:42` — A2 try/except without recovery. Let this throw or catch the specific error at the boundary.

Avoid:

This code is generally good, but here are some suggestions...

Interaction with other skills

Several patterns sit on the seam between anti-slop and humanizer. Both skills cover label-colon bullets, em-dashes, decorative emoji, rule-of-three, and hedging — they catch the same shapes from different angles. The split is by what in the output you are working on:

ConcernOwned by
Structure: headings, bullets, lists, tables, banners, file artefacts, PR/ADR/ticket shape, code identifiers, comments, logs, repl shapeanti-slop
Prose shape: sentence rhythm, vocabulary, stock phrases, narrative voice, paragraph length variancehumanizer
The seam (em-dash density, label-colon runs, emoji headings)anti-slop owns the hard rule, humanizer owns the prose-level audit
Scope and over-explanation in chat repliesanti-slop (catalogue C)
Code, comments, types, identifiers, runtime narration (logs, debug prints)anti-slop (catalogue A)
Test names, setup ceremony, mocking, snapshots, AAA commentsanti-slop (catalogue E)
Doc structure (headings, bullets, TOC, glossary, metadata blocks, PR templates)anti-slop (catalogue B)
Doc prose body (paragraphs, opening sentences, narrative arc)humanizer
Outbound publish gate (Confluence / Slack / Jira)humanize-deliverables (sha256 hard gate via humanize-gate.sh)
Material factual uncertainty and authorization boundariesinference-discipline
Visual / UI / design slopa dedicated visual-design reviewer

When a single artefact mixes prose and structure (PRD, ADR, exec memo): run anti-slop first for the structural pass, then humanizer for the prose paragraphs. The catalogues do not conflict; they catch different surfaces of the same draft.

For prose that ships outbound (Confluence / Slack / customer / leadership), humanize-deliverables is the publish-time hard gate. It runs orthogonally to anti-slop — anti-slop catches the structural slop pre-write, humanize-gate catches the prose tells pre-publish. Both must pass.

If multiple skills apply, run the specific skill first, then anti-slop as the final structural gate.

Final rule

A clean output should feel like it came from a competent maintainer under time pressure: specific, boring where boring is good, and ruthless about anything that does not pay rent.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.