AI Slop Review Skill
An Agent Skill bundle that catches AI slop in prose and enforces conventions for clear writing. It works on any text, such as a Markdown draft, documentation, or a blog post, and adds a scientific layer for empirical software engineering papers (voice and tense, statistical reporting per APA/IEEE/ACM, citations) and a LaTeX layer for LaTeX source (BibTeX, \citeauthor, % GROUNDING). Both load automatically for .tex source, and --scientific opts a non-LaTeX manuscript into the scientific layer. Optional layers apply rules based on ASD-STE100 Simplified Technical English (--ste) and core advice from Writing with Style: The Economist Guide (--economist) to any input. Agent Skills is an open standard originally developed by Anthropic and now read by Claude Code, Cursor, GitHub Copilot, OpenAI Codex, and pi, among others. The client list names the rest.
The skill keeps its writing rules in layers (listed under Rule layers below) and fetches a general AI trope catalog (named patterns such as negative parallelism, em-dash addiction, and rule-of-three groupings, each tagged with a status) at runtime from tropes.fyi and from no other source. The table under Rule layers shows which layers each input loads, and review-repo never loads the LaTeX layer. The same bundle therefore reviews a Markdown blog draft, a non-LaTeX manuscript (with --scientific), or a full LaTeX paper.
Stylistic checks require a problem in context and a replacement that preserves the argument, including purpose, distinctions, emphasis, and voice. Word matches, catalog statuses, and counts prompt inspection; they do not require rewriting a passage that already works. Explicit conventions such as spelling and citation syntax still apply, and reviews identify those corrections separately from clarity problems.
Rule layers
The writing rules ship as five layers. Which of the first three load depends on whether the input is LaTeX source (detected automatically by scripts/detect_scope.py) and whether you pass --scientific:
| Input | general | scientific | latex |
|---|
LaTeX source (.tex) | yes | yes | yes |
| Anything else, no flag | yes | no | no |
Anything else, --scientific | yes | yes | no |
rules-general.md applies to any prose (vocabulary, punctuation, structure, tone). Every rule carries a stable key (G.semicolons, S.significant, L.grounding-comments) that reports, cross-references, and the self-checks cite alongside its name. rules-scientific.md adds research article conventions (verb tense by section, citations, statistics, figures and tables, threats to validity). rules-latex.md adds LaTeX source mechanics (LaTeX quotes, \citeauthor, % GROUNDING, BibTeX). A LaTeX paper is always treated as a research article, so the scientific layer loads automatically. For a non-LaTeX manuscript (Markdown or PDF), --scientific opts into it.
rules-ste.md is the optional STE layer, and --ste adds it to any row of the table. It applies part of ASD-STE100 Simplified Technical English: short sentences with the subject and verb near the start, active voice, one topic per paragraph, one meaning per word, verbs instead of nominalizations, and no dropped articles. It changes the ASD-STE100 rules on sentence length and style. Sentence length varies around a target of 25 words, with a tolerance up to 35. Each unit (a reply, a headed section, or a text without headings) carries one stylistic device at most. Quotations and literal strings stay as written. Where the STE layer and the general layer set different limits for the same construction, the STE limit applies. The STE rules carry T. keys.
When an STE rewrite of an existing sentence would lose meaning, precision, or force, the sentence stays as written, and a review lists it for author judgment. scripts/scan_sentences.py lists the candidates that a count or a word pattern can find: sentences over 25 words, runs of sentences of similar length, passive verbs, and a light verb followed by an action noun ("make a decision").
rules-economist.md is the optional Economist layer, selected by --economist.
It distills the core advice in Lane Greene's Writing with Style: The Economist
Guide (2023): explain unfamiliar knowledge to intelligent readers, choose plain
and precise words, make actors and actions clear, connect the argument, remove
padding, use a civil tone, and put numbers in context. It also checks numerical
precision and comparability. The rules carry E. keys and include a self-check.
The book is not bundled and is not needed at runtime.
Economist mode keeps project and academic conventions, including the default
American spelling and required statistical detail. It sets no sentence-length
limit, numerical quota, or automatic rounding rule. --economist --ste combines
both optional layers, retaining the stricter STE limits. An unresolved fact or
interpretation goes under author judgment instead of a speculative rewrite.
Examples:
/ai-slop:review draft.md --economist
/ai-slop:review paper.pdf --scientific --economist
/ai-slop:review-diff main --economist
/ai-slop:review-repo --economist
/ai-slop:writing --economist
/ai-slop:init --economist
Versioning
The bundle uses CalVer with a per-month revision counter: YYYY-MM for the first release of a calendar month (the implicit rev0), then YYYY-MM_rev1, YYYY-MM_rev2, ... for subsequent releases that month. The version string appears in eleven callsites, kept in sync by the smoke suite: plugins/ai-slop/.claude-plugin/plugin.json (canonical), .claude-plugin/marketplace.json, the version field of each of the eight SKILL.md files, and the **Skill version:** line in review/SKILL.md's report template. export_rules.py and build_writing.py read the version from plugin.json when they write a file. Git tags follow the same scheme. The pi package manifest (package.json) has no version field, because pi pins a git install to a tag.
Dependencies
The skills call small Python 3 helpers under plugins/ai-slop/scripts/ for deterministic checks (LaTeX root and scope detection, the trope catalog download, BibTeX required-field verification, reference verification against CrossRef and DBLP, the check of grounding quotes against their sources, Markdown linting of the generated report and bundled rules). Requirements:
python3 (latest stable, and CI pins to 3.14). The first-party helpers are stdlib-only. The Markdown linter is PyMarkdown, vendored pure-Python with its dependencies under plugins/ai-slop/scripts/_vendor/. Both lint_markdown.py and the maintainer-side check_baseline.py run against that vendored tree. Both, together with refresh_vendor.py, the vendored tree, and bundled_licenses/, are synced from the upstream pymarkdown-skill repo and are not edited here. Users do not need to pip install anything.
No other runtime dependencies. Three helpers reach the network: the reference check (verify_references.py, CrossRef and DBLP), the grounding quote check (check_quotes.py, for a quote with a URL as its source), and the trope catalog download (fetch_tropes.py, tropes.fyi, which export_rules.py calls as well). Offline the reference check degrades cleanly and reports unchecked-offline, and the review still completes. The catalog download is required. The catalog has one source and no bundled copy, so the run stops when fetching the catalog fails, unless you pass a catalog file with --tropes=<path>. fetch_tropes.py accepts only a body structured like the catalog (a title and its trope headings) and prints the size, heading count, and content hash of what it accepted to stderr, which makes a changed catalog visible. The catalog is third-party text that the skills hand to the model as rules to apply. A paper repository that needs a reproducible review keeps its own copy and passes it with --tropes. Smoke tests for the helpers are at plugins/ai-slop/scripts/tests/run_smoke.py and can be run with python3 plugins/ai-slop/scripts/tests/run_smoke.py.
Install as a Claude Code plugin
/plugin marketplace add se-uhd/ai-slop-skill
/plugin install ai-slop
Eight slash commands become available:
/ai-slop:review
/ai-slop:review-diff
/ai-slop:review-repo
/ai-slop:revise
/ai-slop:ground
/ai-slop:glossary
/ai-slop:writing
/ai-slop:init
review, review-diff, and writing detect LaTeX source automatically and load all three rule layers for it. Any other input loads the general layer. Add --scientific to also apply the research article rules to a non-LaTeX manuscript (a Markdown or PDF paper). review-repo is the whole-codebase mode and always loads the general layer (--scientific optional). It never loads the LaTeX layer, since it reviews the prose and code comments of a repository rather than a single paper. --ste and --economist add their optional layers in review, review-diff, review-repo, writing, and init.
Run them from your project directory. /ai-slop:review finds the document to review in the current directory (a LaTeX root or a PDF, while a Markdown or plain-text draft needs an explicit path), walks the full draft against the rules, and writes a structured Markdown report to ai-slop-report.md in the working directory. /ai-slop:review-diff does the same but only on the lines that you changed in the git working tree (default base HEAD, or any git ref passed as an argument to compare against a different baseline, e.g., /ai-slop:review-diff main). /ai-slop:review-repo sweeps a whole repository instead of one document: its Markdown, plain-text, and LaTeX files, the comments in its source and config files, and its commit messages, with findings grouped by file and by commit (see /ai-slop:review-repo below). /ai-slop:revise reads the report and applies its suggested revisions to the source. The review modes write the same report schema. /ai-slop:glossary creates or maintains GLOSSARY.md from a document, proposes definitions, and checks the document for competing terms and new names for existing concepts, using that report schema for source suggestions. For LaTeX papers, /ai-slop:ground fills the grounding comments that the review flags as missing. Review finds the \cite{} calls missing a grounding comment, and ground fills them by fetching each cited source and inserting a retrieved verbatim quote (or a TODO verify -- <reason> stub when the source cannot be retrieved). /ai-slop:writing is a one-shot setup command. It copies the bundled writing rules into a project-local WRITING.md and adds a reference to it in the AGENTS.md of the repository, with a CLAUDE.md import for Claude Code so collaborators and any Agent Skills client see the conventions even without this plugin installed. /ai-slop:init sets up the general rules and the trope catalog for the current client across projects, using the rules directory of Claude Code or a file referenced by the global instructions of Codex or pi (see /ai-slop:init below). Explicit paths can be passed as arguments to override the auto-detection. The skills also auto-trigger on matching prompts (e.g., "audit this draft for AI slop", "check my edits before I commit", "apply the review report", "ground the citations", "set up writing rules in this repo").
To pick up a new release, refresh the marketplace catalog and reload plugins:
/plugin marketplace update ai-slop
/reload-plugins
The marketplace update reports (1 plugin bumped) when a new version is found and installs it. /reload-plugins activates the new skills in the running session. To skip the manual refresh, enable auto-update for the marketplace: run /plugin, open the Marketplaces tab, select ai-slop, and choose Enable auto-update. Claude Code then refreshes the marketplace and installs the latest plugin version at startup.
Install in Codex
Codex accepts the existing Claude-compatible plugin and marketplace manifests, so both clients install the same bundle. With a Codex CLI that provides codex plugin:
codex plugin marketplace add se-uhd/ai-slop-skill
codex plugin add ai-slop@ai-slop
For a local checkout, pass its absolute path instead of se-uhd/ai-slop-skill to the marketplace command. In Codex, use /skills or type $ to select one of the eight ai-slop: skills, then provide the path and flags. For example, select ai-slop:review and add draft.md --ste. The /ai-slop: examples throughout this README are Claude Code slash commands. In Codex they refer to the corresponding skill. Natural-language requests can activate the skills in both clients.
See the official plugin installation guidance and Codex skill invocation guidance. Python 3 and the network requirements listed above apply to both clients.
Install in pi
The repository root is a pi package whose package.json points pi at the eight skills. Install it from a release tag, replacing <tag> with a tag from the tag list:
pi install git:github.com/se-uhd/ai-slop-skill@<tag>
Without @<tag>, pi follows the default branch instead of a release. pi -e git:github.com/se-uhd/ai-slop-skill loads the package for one session without adding it to your settings. For a local checkout, pass its absolute path to pi install.
Pi names the skills after their directories, so invoke them with /skill:<name> followed by the path and flags, for example /skill:review draft.md --ste. The /ai-slop:<name> examples throughout this README correspond to /skill:<name> in pi. Natural-language requests can activate the skills as well.
A tag pins the install, and pi update does not move it. To pick up a new release, run pi install again with the new tag. Pi identifies a git package by its URL without the ref, so the new tag replaces the old one. pi update git:github.com/se-uhd/ai-slop-skill updates an install without a tag.
If another installed package provides a skill with the same name, such as review, pi keeps the skill that it discovers first and shows a warning at startup. Run pi config to disable one of the two. Python 3 and the network requirements listed above apply to pi as well. /skill:ground fetches the cited sources, so pi needs a way to read web pages, such as a web-fetch extension or shell access to a tool like curl.
Use in other Agent Skills clients
The skills follow the Agent Skills specification. The plugins/ai-slop/ bundle contains eight workflows under skills/, with shared content in shared/ and helper scripts in scripts/. Keep the whole bundle together. Copying a single skill directory omits its shared dependencies. Each workflow resolves bundled paths from the location of its own SKILL.md supplied by the client, and runs helpers by absolute path while keeping the user's project as the working directory. No Claude-specific environment variable is needed.
For Claude Code, Codex, and pi, use the installation instructions above. For another client, register the eight skill directories while preserving their relative paths to shared/ and scripts/. The Agent Skills client list links to each client's installation instructions.
Use as a system prompt
For chat UIs or LLM APIs without Agent Skills support, paste the contents of the rule layers (rules-general.md, plus rules-scientific.md, rules-latex.md, rules-economist.md, and rules-ste.md as your text calls for) and the catalog from tropes.fyi into the system prompt. The catalog page has a download button, and the file behind it is plain markdown formatted for system-prompt use. /ai-slop:init <path> writes the general layer and the catalog into one file at <path>, ready to paste or to add to a claude.ai Project as knowledge.
Skill workflows
Conventions specific to one project, such as a venue's structural requirements (e.g., EMSE structured abstracts), preferred terminology, or a project glossary, belong in the AGENTS.md of the project. A CLAUDE.md containing @AGENTS.md also loads them in Claude Code, including older versions. This repository uses that arrangement for its maintainer guidance.
/ai-slop:review
Given a document (LaTeX, PDF, or plain text), the review skill:
- Loads the rule layers that the scope calls for, each carrying its own self-check:
shared/rules-general.md (language, restricted vocabulary, terminology, active voice, punctuation, structure, tone), shared/rules-scientific.md (the "significant" caveat, verb tense by section, citation style, statistical reporting per APA/IEEE/ACM, figures and tables, threats to validity), and shared/rules-latex.md (LaTeX quotes, caption punctuation, cross-reference and \citeauthor macros, % GROUNDING, BibTeX). The table under Rule layers shows which layers each input loads, and --ste adds shared/rules-ste.md to any row.
- Loads the AI trope catalog via
scripts/fetch_tropes.py, which reads the rendered viewer at https://tropes.fyi/tropes-md and unwraps the catalog from the page. That is the only source. When fetching the catalog fails, the review stops rather than falling back to something older. To override for a single run, pass --tropes=<path> (repeatable for multiple files). The named files replace the live catalog and are concatenated in the order given.
- Walks the document section by section, with deterministic scans for the patterns that a reader misses (Unicode glyphs, unanchored references, and sentences pasted from one place into another), recording each violation as a finding with
Rule, Location (file:line for text source, Section: <name> for PDF), Quote (verbatim, unique within the document), and Suggested revision (concrete replacement text).
- Computes cross-cutting metrics (dash density counting em-dashes and ASCII dashes, colon and semicolon density, the combined pause-mark count, restricted-word density per paragraph, sentence-length variance, verb-tense compliance, American-vs-British spelling, the "significant" audit, citation grounding, and, with
--ste, the STE sentence metrics) and, for LaTeX, a grounding to-do list of ungrounded \cite{} calls plus a CrossRef/DBLP reference check for hallucinated or mismatched citations.
- Writes
ai-slop-report.md in the working directory with a stable schema so revise mode can act on it.
Review mode does not modify the document. The report is the only output, apart from adding its name to the top-level .gitignore when that line is missing.
/ai-slop:glossary
Run /ai-slop:glossary without a filename to search the working directory and
relevant subdirectories for the main document. The skill uses project
instructions, the README, build configuration, and document content to identify
the main LaTeX, PDF, Markdown, or plain-text work. It prefers editable source
over a PDF of the same document and follows the files that a LaTeX root includes. A clear
candidate is used directly, with a question only when discovery finds no document
or leaves genuine ambiguity.
Glossary mode reads a paper or document, groups its terms by concept, and creates
or maintains GLOSSARY.md. Definitions carry source locations and supporting
passages, with inferred definitions and naming preferences marked as proposed.
Existing definitions, distinctions, accepted abbreviations, and scoped vocabulary
restrictions are preserved rather than replaced by newly extracted preferences.
The same invocation validates the document against the glossary and writes
ai-slop-report.md with concrete source suggestions and questions for the author.
The check includes synonyms, conflicting meanings, undefined technical terms,
and newly invented names for concepts that already have a term. It compares
meanings in context, so a glossary need not enumerate every future coinage and the
ordinary sense of a word is not automatically forbidden. The document stays
unchanged, and /ai-slop:revise can apply concrete source suggestions.
/ai-slop:glossary
/ai-slop:glossary main.tex
/ai-slop:glossary draft.md
/ai-slop:glossary draft.md --check
/ai-slop:glossary paper.pdf --glossary=terminology/GLOSSARY.md
--check validates against an existing glossary without editing it.
--glossary=<path> selects a glossary instead of GLOSSARY.md in the working
directory. Glossary mode works offline and loads the general terminology rules
without fetching the trope catalog. The glossary is maintained project content,
while the generated report is ignored by git. Ordinary review, diff, and repository
reviews also consult the applicable project glossary when checking terminology.
/ai-slop:review-diff
Diff mode is a variant of /ai-slop:review for git-versioned documents. Instead of walking the full draft, it runs git diff <base> (default HEAD) and restricts the rule and trope checks to the lines that you added or modified in .tex, .md, and .txt files. All three layers apply to the changed .tex files and the general layer (plus the scientific layer with --scientific) to the rest, so a code repository with one paper under a subdirectory still gets its Markdown changes reviewed. The output is the same ai-slop-report.md schema with one extra header line (**Diff scope:** base=<ref>, files=<list>), which lets /ai-slop:revise apply the suggestions unchanged.
A finding is in scope only when at least one line of its quote falls on a changed line. Pre-existing issues on untouched lines are not reported. Cross-cutting metrics that need full-document context (e.g., em-dash density per page, sentence-length variance over runs of three sentences) are skipped, and only newly added or modified \cite{} calls are checked. Diff mode requires a git working tree. Outside one, fall back to /ai-slop:review.
/ai-slop:review-repo
Repo mode is the whole-codebase counterpart to review and diff modes. Instead of one document, it runs scripts/scan_repo.py to extract the natural-language text of the repository: every Markdown, plain-text, and LaTeX file in full, the comments and doc-comments of the source and config files, and the commit messages. The comment languages are Shell, Java, Kotlin, Python, JavaScript, and TypeScript; the C family, Go, Rust, Swift, Scala, Dart, Groovy/Gradle, Ruby, PHP, Perl, R, Lua, and Lisp/Clojure; HTML/XML, Vue/Svelte, CSS/SCSS/Less, and SQL; and config formats such as YAML, TOML, INI, .properties, Dockerfile, and Makefile. The COMMENT_SPECS/NAME_SPECS tables in scan_repo.py are the authoritative list. Repo mode then scans that prose against the general rules and the trope catalog and writes ai-slop-report.md with findings grouped by file (### <relpath>) and by commit (### commit <short-sha>), plus a **Repo scope:** header line. Comment detection is string-aware. A // or # inside a string literal is not mistaken for a comment. In Markdown, a fenced block with a prose format (e.g., markdown, text) as its info string is read as prose, so a quoted template is content. Other fenced code is skipped.
In a git repository the scan covers the tracked files, so .gitignored build output and dependencies are excluded automatically. Outside one it walks the whole tree. In both cases it skips a denylist of vendored, build, dependency, and test-fixture directories. Generated files (a DO NOT EDIT or @generated marker on a comment line in the first ten lines, each named on stderr), lockfiles, dependency pins, and binaries are skipped. LaTeX (.tex) files are reviewed as prose (body and % comments) against the general rules. /ai-slop:review remains the dedicated LaTeX tool for citations, BibTeX, and section-aware checks. Commit messages are scanned too: the subject and body of each commit, with merge commits and the standard trailer lines (Co-authored-by, Signed-off-by, ...) dropped. The default covers the most recent 200 commits. --commits=<N> sets another count, --commits=all the full history, --commits=<range> a git revision range (e.g. main..HEAD for one branch), and --no-commits turns it off. Pushed history is rewritten only by a deliberate repair, so commit message findings are advisory (a guide for future messages, or for rewording the unpushed commits on a branch) and are not something revise applies. Because the report spans many files, /ai-slop:revise (a one-document-at-a-time tool) does not auto-apply it. Fix each file directly, or run /ai-slop:revise ai-slop-report.md <file> for one file, which applies the findings under the heading for that file. This mode catches the slop that a diff review never revisits: a British spelling, an em-dash, or a trope that has been in a committed comment or a commit message for many commits.
/ai-slop:revise
Given a previously generated report and the source of the document (LaTeX, Markdown, or plain text), the revise skill:
- Parses the report, extracting the per-section findings.
- Locates each
Quote in the document using the Location hint in the report to disambiguate.
- Applies the
Suggested revision with one edit or patch hunk per finding (so each change is one diff hunk).
- Inserts
% GROUNDING: TODO verify <key> stubs (LaTeX only) after the ungrounded \cite{} calls listed in the grounding to-do of the report, for the author to fill, or for /ai-slop:ground to replace with retrieved quotes.
- Skips findings with a
Quote that cannot be located uniquely or a suggestion that would break the markup (e.g., LaTeX), with reasons logged in the summary.
- Skips items in "Items requiring author judgment" (they need manual decisions).
- Prints a summary of applied, skipped, and author-judgment-required findings.
Revise mode does not regenerate the report and does not commit. The user runs git diff to inspect and git commit to keep the changes.
/ai-slop:ground
Given a LaTeX root, the ground skill fills the grounding comments that the review flags as missing:
- Extracts the citations with
scripts/extract_cites.py, which resolves the root, follows \input / \include, and emits, per cited key, the claims that the surrounding sentences attribute to it and the BibTeX metadata (title, author, year, DOI, URL) needed to find the source.
- Fetches each source with one agent per cited key, chunked into small slices to stay under rate limits. Each agent retrieves the source (online, or a user-supplied local file for a paywalled article or book) and copies a short verbatim quote that supports the claim.
- Checks each quote against its source with
scripts/check_quotes.py, which re-reads the file or page that the agent named and confirms that the quote occurs in it. A quote that it cannot find is downgraded to a TODO verify -- unverified stub, and a source that it cannot read as text (a PDF) is handed back for the skill to check by hand.
- Writes the comments back with
scripts/insert_grounding.py, inserting % GROUNDING: <key> -- "<quote>" after each ungrounded \cite{} call and replacing any TODO verify stub left by revise mode or an earlier run (idempotently, matching indentation).
The anti-fabrication rule is mandatory. A quote is written only when the source was actually retrieved, and the check in step 3 enforces it wherever the source is text. Otherwise the comment is % GROUNDING: <key> -- TODO verify -- <reason> (paywalled, abstract-only, book, not-found, source-does-not-support, or unverified), never a quote from memory. A source-does-not-support result is reported as a finding rather than a gap, because it flags a likely miscitation. Ground mode is LaTeX-only and does not commit. The user inspects the edits with git diff. The grounding agents search the web with the claim sentences, so text of an unpublished manuscript leaves the machine. For a draft that must stay on the machine, use local sources.
/ai-slop:writing
The writing skill is a one-shot setup command for new (or existing) project repositories. With scripts/build_writing.py, it builds a project-local WRITING.md by concatenating the bundled writing rules (the layers selected automatically: all three for a LaTeX project, the general layer otherwise, general + scientific with --scientific, or the general layer alone with --general for a code repository that happens to contain a paper, with the Economist layer added by --economist and the STE layer by --ste) with the AI trope catalog (fetched live from tropes.fyi), then creates or updates AGENTS.md with an instruction to read WRITING.md. It also creates a CLAUDE.md import of AGENTS.md, or preserves an existing Claude reference to the rules. An existing AGENTS.override.md receives the reference too, because Codex and pi read it instead of AGENTS.md, even when it is empty. All three clients can use the generated rules without this plugin installed and when offline.
WRITING.md is meant to be edited freely after generation. It is a starting point, not a synced replica. The skill confirms before overwriting an existing WRITING.md, and the instruction-file updates are idempotent. Existing instructions are preserved, and references already present are not appended again. The writing skill does not modify your content and does not commit.
/ai-slop:init
Init mode sets up the rules for the current client across projects, so that the assistant's replies in chat, the files it edits, its code comments, and its commit messages follow the rules without a review afterward. scripts/export_rules.py combines the general layer with the AI trope catalog (fetched live from tropes.fyi), each under its own heading, below an instruction to apply the rules to the text that the assistant writes or changes, and to let the writing conventions of the project itself take precedence. --economist adds the core Economist advice, and --ste adds the STE layer. Both flags can be combined. The file leaves out the self-check of each layer, which restates the rules item by item, and asks for the check in its opening paragraph instead. It also drops the status line of each catalog entry, its **Avoid patterns like:** label, and the --- line after it. The file carries no rules for a single genre or file format. The scientific and LaTeX layers belong to a paper project and stay with /ai-slop:writing.
In Claude Code, the default output remains ~/.claude/rules/ai-slop.md. Claude Code reads every Markdown file under ~/.claude/rules/ at launch, in every project, so the rules load without an import in any CLAUDE.md. A path under .claude/rules/ in a repository loads the file in that project only, and any other path writes the file for another use, such as knowledge for a claude.ai Project or an @<path> import. Running the mode again replaces the file with the current rules and catalog. The mode also replaces a file from /ai-slop:export, its former name. The skill asks before replacing any other file, so keep your own additions in a separate file. The general layer and the catalog come to about 20,000 tokens, which every session carries in its context. The file takes effect in the next session.
In Codex, the default output is <codex-home>/ai-slop.md, with CODEX_HOME or ~/.codex determining the home directory. After exporting successfully, the skill appends an instruction to read that file to the effective global instruction file: a nonempty AGENTS.override.md if present, otherwise AGENTS.md. It preserves existing instructions and adds the reference only once. The full rules stay in the export file, so the global instruction file stays small and a later run replaces the rules without touching your own instructions. See Codex instruction discovery. Start a new session to use the setup automatically.
In pi, the default output is <pi-agent-dir>/ai-slop.md, with PI_CODING_AGENT_DIR or ~/.pi/agent determining the agent directory. After exporting successfully, the skill appends the same read instruction to the first global context file that pi loads from that directory: an existing AGENTS.override.md, which pi reads even when it is empty, then AGENTS.md (or AGENTS.MD), then CLAUDE.md (or CLAUDE.MD), and otherwise a new AGENTS.md. It preserves existing instructions and adds the reference only once. The rules stay in a separate file so the global context file stays small and a later run can replace them without touching your own instructions.
An explicit output path exports the file without changing the global instructions of Codex or pi. Run init in each client to set it up there, or name the target client in the request. The skill does not change the global configuration of any other client.
/ai-slop:writing writes a WRITING.md into one project, with the layers that the project calls for, for co-authors to read, edit, and commit. /ai-slop:init writes one file for every session and replaces it on each run.
Repository layout
The plugin is under plugins/ai-slop/: skills/ holds the eight SKILL.md workflows (review, review-diff, review-repo, revise, ground, glossary, writing, init), which Claude Code offers as the /ai-slop: slash commands, and shared/ the five rule layers plus the rationale doc. scripts/ holds the vendored Markdown linter under _vendor/ and the stdlib Python helpers for scope and LaTeX root detection, repository prose extraction (scan_repo.py), the glyph, reference, repeat, and sentence scans (scan_glyphs.py, scan_reference.py, scan_repeats.py, scan_sentences.py), the trope catalog download, the export of the rules as one file (export_rules.py), the assembly of WRITING.md (build_writing.py), the citation, BibTeX, and reference checks, citation extraction, the grounding quote check, and grounding-comment insertion. The marketplace manifest is at .claude-plugin/marketplace.json and the plugin manifest at plugins/ai-slop/.claude-plugin/plugin.json. The root package.json is the pi package manifest, which lists plugins/ai-slop/skills under its pi.skills key.
Maintainer notes
Refreshing the vendored Markdown linter
The bundled _vendor/ tree under plugins/ai-slop/scripts/ holds PyMarkdown plus its pure-Python deps. Like the other upstream-owned paths that AGENTS.md lists, it is refreshed in pymarkdown-skill, which pins the vendored versions and builds the tree with its refresh_vendor.py. To pull a newer release, release it there and sync it in from a checkout of that repo:
/path/to/pymarkdown-skill/sync/sync_to_skill.sh --target plugins/ai-slop/scripts/
The sync replaces lint_markdown.py, check_baseline.py, refresh_vendor.py, _vendor/, and bundled_licenses/, keeps schema_checks.py, lint_markdown.yaml, and tests/, and records the upstream release in scripts/.pymarkdown-skill-version. Do not run the synced refresh_vendor.py here, because a tree refreshed in this repo matches no upstream release and the next sync overwrites it.
Bump the version at the eleven callsites listed in the Versioning section. The next rev is the highest existing rev for the month plus one, with the bare YYYY-MM tag as rev0. After committing the bump, create the matching tag (git tag YYYY-MM_revN) and push it. Every release commit gets one, and tags must stay ancestors of main. Never amend or rebase a commit that has already been tagged or pushed. Additional work goes into a new rev with its own commit and tag.
Validating the manifests
Before committing changes to the manifests, validate them:
claude plugin validate plugins/ai-slop
claude plugin validate .claude-plugin/marketplace.json
To check the pi manifest, run pi -e . from the repository root. Pi lists the eight skills at startup and reports any skill warnings.
If a user reports Failed to install: This plugin uses a source type your Claude Code version does not support, do not assume that the problem is the source field. Claude Code emits that same message for any unrecognized key in either manifest. Run claude plugin validate first. The validator reports the real error.
Acknowledgements
The general AI trope catalog is the work of Ossama Chaib at tropes.fyi. This skill fetches the catalog at runtime and bundles no copy of it. All credit for the trope catalog goes to him. The layered writing rules (rules-general.md, rules-scientific.md, rules-latex.md, rules-economist.md, rules-ste.md) are maintained by the Software Engineering Group at Heidelberg University. The STE layer adapts writing rules from the ASD-STE100 Simplified Technical English specification, which ASD maintains, and reproduces neither the specification nor its dictionary. The Economist layer distills core advice from Lane Greene's Writing with Style: The Economist Guide (2023), chiefly the introduction and chapters 1 through 5, into rules and examples written for this bundle. The book is not distributed or needed at runtime.
License
First-party content is licensed under CC BY 4.0. See LICENSE.
Third-party software bundled under plugins/ai-slop/scripts/_vendor/ is distributed verbatim under its own licenses (MIT, BSD-3-Clause, PSF-2.0). See plugins/ai-slop/scripts/_vendor/NOTICE for per-package attribution and full license texts.
The AI trope catalog is third-party content by Ossama Chaib at tropes.fyi, and it does not declare an explicit license. No copy of it is redistributed here. plugins/ai-slop/scripts/fetch_tropes.py fetches it at review time and passes it to the model, which is the use that upstream states on the page ("Add this file to your AI assistant's system prompt or context"). All rights to the catalog remain with the original author.
