<div align="center">

avoid-ai-writing

Audit & rewrite content to remove AI writing patterns. A practical skill for any AI agent. Supports detect-only and edit-in-place modes, plus voice profiles.

<img src="docs/demo.gif" alt="The bundled detector engine flagging 13 AI-writing patterns by category in a sample paragraph, then scoring the clean rewrite 0/100" width="800"> </div>

---

A portable writing skill for Claude Code, OpenClaw, Hermes, and any other agentskills.io-compatible agent. Audits and rewrites content to remove AI writing patterns ("AI-isms").

Three modes:

• Rewrite (default) — flags AI patterns and rewrites the text to fix them. A built-in second pass catches patterns that survived the first edit.
• Detect — flags AI patterns without rewriting. Shows which flags are real problems vs. judgment calls. Useful when patterns might be intentional, when auditing content you don't want altered, or when you just want a quick scan.
• Edit — edits a prose file in place (via the Edit tool) with minimal, targeted changes, preserving passages that are already human. Source code, configuration, and generated data are refused because prose rewrites can corrupt structured content. Returns an edits-made + verification report, not the full file.

An optional voice profile (casual / professional / technical / warm / blunt) sets how the prose should sound, independent of the audience context profile.

Quick demo

Input:

Certainly! Acme Analytics, a vibrant startup nestled in the heart of Boulder's thriving tech ecosystem, has secured $40M in Series B funding — marking a watershed moment for the observability landscape. The platform serves as a unified hub, featuring real-time dashboards, boasting sub-second queries, and presenting a seamless integration layer. Moreover, experts believe Acme is poised to disrupt the market. In conclusion, the future looks bright!

Output:

Acme Analytics raised a $40M Series B led by Sequoia. The Boulder-based startup makes an observability platform that runs queries in under a second and plugs into existing monitoring stacks without custom integration work.

What it caught: chatbot opener ("Certainly!"), promotional language ("vibrant," "nestled," "thriving"), significance inflation ("watershed moment"), copula avoidance ("serves as," "featuring," "boasting"), 4 word replacements, vague attribution ("experts believe"), filler ("Moreover"), generic conclusion ("the future looks bright"), over-polished uniformity. 15+ AI tells in one paragraph.

Why a skill, not just a prompt

A one-shot "make this sound human" prompt catches the obvious stuff. This skill is different:

• Structured audit — returns identified issues with quoted text, the rewrite, a change summary, and a second-pass audit in four discrete sections. You see exactly what changed and why.
• Two-pass detection — the second pass re-reads the rewrite and catches patterns that survive the first edit: recycled transitions, lingering inflation, copula swaps that snuck through.
• 112-entry word replacement table across 3 tiers + 10 Tier 3 phrases — not vibes-based. Every flagged word has a specific, plainer alternative. "Leverage" → "use." "Commence" → "start." Tier 1 words always flag, Tier 2 words flag when they cluster, Tier 3 words flag only at high density. Tier 1 itself splits into 1A frequency markers (delve, tapestry) and 1B clarity edits (in order to, utilize) — same fix, but only 1A is evidence about how a passage was produced, and 1B is weighted lower so a wordiness fix cannot push a document toward an AI classification. Tier 3 phrases (multi-word boilerplate like "the integration of," "decentralized compute") flag on per-phrase repetition or when 3+ distinct phrases stack in one piece — the LLM-self-varies-boilerplate shape.
• 62 pattern categories — representative examples below, each with before/after. Includes structural detection (hashtag stuffing, bare-NP bullet lists, hedge-stacked predictions), AI-tool fingerprints (placeholders, citation markup, UTM params), rhythm/uniformity checks, conversational-register tells, and writer-side tests. The full catalog lives in SKILL.md; this count is enforced against it in CI.
• Detect mode — flag patterns without rewriting. See which flags are real problems vs. judgment calls. Useful when patterns might be intentional or you're auditing content you don't want altered.
• Works across platforms — one SKILL.md runs in Claude Code, Cowork (as a plugin), OpenClaw, Cursor (as a ported rule), and more via npx skills add. See the install paths below.

Installation & Usage

Quick install — any agent

The fastest way to install this skill, and later keep it updated, is the community skills CLI. It auto-detects installed coding agents and supports 75+ of them, including Claude Code, Codex, Cursor, OpenClaw, and Hermes. npx downloads and runs that package from the npm registry. It's third-party code, not something this repo publishes or maintains. The commands below pin skills@1.5.23 rather than @latest so the installer version that runs is fixed and visible; the skill payload still follows this repository's current default branch. Bump the pin yourself once you've checked the release notes. It requires Node >=22.20.0, a higher floor than this repo's own >=18; check with node --version if you're not sure which you have.

npx skills@1.5.23 add conorbronsdon/avoid-ai-writing

For this public repository, the CLI normally uses its GitHub blob fast path and installs only SKILL.md. If that path is unavailable, it can fall back to cloning and install the full root skill directory. Use git clone when you explicitly want the detector, tests, CI config, and other repository tooling; see the manual steps below.

Useful flags:

# Target specific agents instead of everything detected
npx skills@1.5.23 add conorbronsdon/avoid-ai-writing -a claude-code -a codex

# Install globally (~/.<agent>/skills/) instead of the current project
npx skills@1.5.23 add conorbronsdon/avoid-ai-writing -g

Later, npx skills@1.5.23 update refreshes installed skills in whichever scope you select. It prompts for project vs. global; pass -g or -p to choose non-interactively. See the skills update docs for the full command reference.

Prefer to install by hand, or using an agent not covered above? The sections below are manual, per-platform steps that don't need Node or npx.

Claude Code

Option 1: Clone into skills directory

git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.claude/skills/avoid-ai-writing

Option 2: Copy the file directly

Download SKILL.md and place it in any directory that Claude Code can read. Reference it in your CLAUDE.md:

- Editing for AI patterns → read `path/to/avoid-ai-writing/SKILL.md`

Option 3: Use as a slash command

Create a command file (e.g., ~/.claude/commands/clean-ai-writing.md):

---
description: Audit and rewrite content to remove AI writing patterns
---

$ARGUMENTS

Read and follow the instructions in ~/.claude/skills/avoid-ai-writing/SKILL.md

Then use /clean-ai-writing <your text> in Claude Code.

Claude Cowork — install as a plugin

Cowork loads skills only from installed plugins — it doesn't scan ~/.claude/skills/, so a bare clone (the Claude Code steps above) won't be discovered there. This repo doubles as a single-plugin marketplace, so install it as a plugin instead:

/plugin marketplace add conorbronsdon/avoid-ai-writing
/plugin install avoid-ai-writing@conorbronsdon-skills
/reload-plugins   # or restart the session, to activate the skill

In the Cowork desktop app, do the same from Customize → Plugins → Add marketplace from GitHub (conorbronsdon/avoid-ai-writing), then install avoid-ai-writing. The skill auto-triggers from phrases like "remove AI-isms." New releases arrive when the plugin's version is bumped — run /plugin marketplace update to pull them.

The same plugin install works in Claude Code if you'd rather have a versioned, updatable plugin than the file clone above.

Prefer not to install a plugin? Copy SKILL.md into a folder connected to your Cowork session and tell the agent to follow ./SKILL.md — works as a one-off, no auto-trigger.

OpenClaw

Option 1: Install from ClawHub

clawhub install avoid-ai-writing

Option 2: Clone into skills directory

git clone https://github.com/conorbronsdon/avoid-ai-writing ~/.openclaw/skills/avoid-ai-writing

Cursor

Drop the ported rule into your project's .cursor/rules/:

mkdir -p .cursor/rules
curl -o .cursor/rules/avoid-ai-writing.mdc \
  https://raw.githubusercontent.com/conorbronsdon/avoid-ai-writing/main/cursor-rules/avoid-ai-writing.mdc

See cursor-rules/README.md for activation globs and trigger phrases. Functionally identical to the Claude Code skill — same tier vocabulary, same context profiles, same modes.

Hermes

Drop the skill into Hermes's skills directory — it then appears automatically as /avoid-ai-writing, no registration needed:

mkdir -p ~/.hermes/skills/writing/avoid-ai-writing
curl -o ~/.hermes/skills/writing/avoid-ai-writing/SKILL.md \
  https://raw.githubusercontent.com/conorbronsdon/avoid-ai-writing/main/SKILL.md

OpenAI Codex

Codex reads Agent Skills in the same SKILL.md format. Put it in .agents/skills/ at the repo root, or ~/.agents/skills/ to use it across all your projects:

mkdir -p .agents/skills/avoid-ai-writing
curl -o .agents/skills/avoid-ai-writing/SKILL.md \
  https://raw.githubusercontent.com/conorbronsdon/avoid-ai-writing/main/SKILL.md

Other agents

The same SKILL.md (or the Cursor .mdc port) drops into most tools' rules/skills location:

| Tool | Where to put it | |------|-----------------| | Windsurf | .windsurf/rules/avoid-ai-writing.md | | Cline | .clinerules/avoid-ai-writing.md | | GitHub Copilot (VS Code) | paste into .github/copilot-instructions.md | | Claude.ai Projects | paste SKILL.md into the project's custom instructions | | ChatGPT Custom GPTs | paste SKILL.md into the GPT's Instructions field |

Triggering the skill

Once installed, ask your assistant to clean up AI writing:

• "Remove AI-isms from this post"
• "Audit this draft for AI tells"
• "Make this sound less like AI"
• "Clean up AI writing in this paragraph"

In rewrite mode (default), the skill returns four sections:

1. Issues found — every AI-ism identified, with the text quoted
2. Rewritten version — clean version with all AI-isms removed
3. What changed — summary of the major edits
4. Second-pass audit — re-reads the rewrite and catches any surviving tells

In detect mode, the skill returns two sections:

1. Issues found — every AI-ism identified, grouped by severity (P0/P1/P2)
2. Assessment — which flags are clear problems vs. patterns t