avoid ai writing

Abstract

Skill that audits and rewrites content to remove AI writing patterns. Use it with your favorite agents including Claude Code, OpenClaw, Codex, and Hermes.

The Problem

Many AI‑generated drafts retain tell‑tale phrasing (“certainly!”, “leveraging”, inflated adjectives) that readers flag as non‑human. Teams that need to publish polished copy or audit compliance must manually hunt these patterns, which is time‑consuming and error‑prone.

What This Does

avoid-ai-writing ships a lightweight detection‑and‑rewrite engine that scans prose for 112 known “AI‑isms” and returns a cleaned version. The core logic lives in detector/patterns.js (regex tables, word‑replacement tiers) and detector/validate.js (orchestrates a first‑pass scan, applies edits, then runs a second‑pass audit). Test suites (detector/patterns.test.js, detector/validate.test.js) confirm that the patterns are applied correctly. The skill is packaged for Claude Code, OpenClaw, Hermes, and any agentskills.io‑compatible agent via the plugin manifest files in .claude‑plugin/marketplace.json and plugins/avoid-ai-writing/.claude-plugin/plugin.json.

How It Is Wired

File	Responsibility	Key Functions / Exports
`detector/patterns.js`	Holds the pattern catalogue (CATEGORIES, regexes, tiered word maps). Exports `PATTERNS` and `WORD_REPLACEMENTS`.
`detector/validate.js`	Entry point for the skill. Imports `PATTERNS`, runs `detect(text)` → list of matches, then `rewrite(text)` applying `WORD_REPLACEMENTS`. Calls itself a second time on the rewritten output for the “two‑pass” audit.
`detector/validate.test.js`	Unit test that drives `validate()` with sample paragraphs, asserting correct flags and edits.
`scripts/check-style.js`	CLI wrapper used by the CI workflow (`.github/workflows/detector-test.yml`). Reads a file, pipes it through `validate()`, and prints a JSON report.
`plugins/avoid-ai-writing/.claude-plugin/plugin.json`	Declares the skill’s public interface (`run` command) for Claude‑compatible agents. The runtime loads `detector/validate.js` when the skill is invoked.
`.github/workflows/detector-test.yml`	Executes `npm test` (Jest) on every push, ensuring the detector stays functional.
`scripts/self-scan.js`	Convenience script that runs the detector on the repository’s own source files (used for internal quality checks).

Call flow for a typical agent request

Agent loads the plugin manifest → identifies run command.
Runtime imports detector/validate.js.
validate(text) → detect(text) (uses PATTERNS).
If mode ≠ detect, rewrite(text) replaces flagged tokens per the tier tables.
Result passes back to the agent; a second call to validate() on the rewrite produces the final audit section.

All filesystem effects are confined to reading the input string and writing the JSON report; no external services or databases are touched. The only module with a broader blast radius is validate.js, because it aggregates pattern data and performs the two‑pass cycle.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/avoid-ai-writing
cd avoid-ai-writing

# Install JavaScript dependencies (npm is implied by package.json)
npm ci   # note: no lockfile, so npm install works but reproducibility is lower

# Run the built‑in demo on a sample file
node scripts/check-style.js examples/prose.json
# → prints a JSON audit with detected patterns and the cleaned rewrite

Configuration – The skill does not require environment variables; all pattern data is hard‑coded in detector/patterns.js. To change the voice profile, edit the voice field in the request payload sent by the calling agent (the skill merely respects the string; no config file is present).

Integration – Agents that read plugins/avoid-ai-writing/.claude-plugin/plugin.json will automatically expose a run endpoint that forwards the user‑supplied text to detector/validate.js.

Real‑World Use

A content‑approval pipeline can invoke the skill as a pre‑commit hook:

# In a CI job
TEXT=$(cat $FILE)
RESULT=$(node -e "const {validate}=require('./detector/validate'); console.log(JSON.stringify(validate(process.argv[1])))" "$TEXT")
if jq -e '.issues | length > 0' <<<"$RESULT"; then
  echo "AI‑style issues detected – fail the build"
  exit 1
fi

The job aborts if any AI patterns remain after the second‑pass audit, guaranteeing that only human‑styled copy proceeds to publication.

Code Health & Issues

Low – Missing lockfile – package.json is present but no package-lock.json or pnpm-lock.yaml; builds may yield different dependency versions.
Low – Limited test coverage – 6 test files exist, focused on the detector; no integration tests for the plugin wrapper or CLI scripts.
Low – No TypeScript – All source is plain JavaScript; static typing could reduce runtime errors in pattern handling.
Low – No explicit linting config – scripts/check-style.js runs a custom style check, but a standard linter (ESLint) is not configured.

No critical security or licensing gaps are visible; the repository includes an MIT license.

The Bottom Line

avoid-ai-writing provides a focused, rule‑based detector and rewrite engine that can be dropped into any Claude‑compatible workflow. It is easy to run locally and is covered by unit tests, but the lack of a lockfile and broader integration tests means production deployments should pin dependencies manually and add end‑to‑end validation. Ideal for teams that need deterministic, audit‑ready AI‑writing cleanup without building their own pattern library.