11 added, 7 removed. Audit A to A.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What this is
- A single-file writing skill (`SKILL.md`) that audits and rewrites content to remove AI writing patterns. The skill is a markdown file consumed by AI coding assistants; the repository also includes a dependency-free deterministic detector and test suite.
+ A directory-based writing skill (`SKILL.md` plus `references/patterns.md`) that audits and rewrites content to remove AI writing patterns. The skill is a markdown file consumed by AI coding assistants; the repository also includes a dependency-free deterministic detector and test suite.
## Repository structure
- - `SKILL.md` — the skill itself. This is the product. All rules, tiers, profiles, and output format live here.
+ - `SKILL.md` — entry instructions, severity tiers, preservation rules, and output formats.
+ - `references/patterns.md` — canonical word tiers, catalog, context and voice profiles.
+ - `SKILL.full.md` — generated full source for comparison and self-scan.
+ - `dist/avoid-ai-writing.md` — generated portable paste instructions.
- `README.md` — public-facing docs, installation instructions, pattern reference table, full before/after example.
- `CHANGELOG.md` — version history with what changed and why.
## How to make changes
- Edit `SKILL.md` directly. When making changes:
+ Edit `SKILL.md` and `references/patterns.md` directly. When making changes:
- Bump the version in the SKILL.md frontmatter (`version: X.Y.Z`)
- - Run `bash scripts/sync-plugin-skill.sh`. Root SKILL.md is the source of truth; the plugin's bundled copy and `plugin.json`'s version are generated from it, and CI fails on a mismatch. Bumping the frontmatter without this step fails the `check` job with `version mismatch: SKILL.md=X plugin.json=Y`.
+ - Run `bash scripts/sync-plugin-skill.sh`. The two canonical files are the source of truth; the plugin's bundled copy and `plugin.json`'s version are generated from it, and CI fails on a mismatch. Bumping the frontmatter without this step fails the `check` job with `version mismatch: SKILL.md=X plugin.json=Y`.
- Run `npm test` to exercise the detector, category contract, validator, corpus helpers, and style checks.
- Add a dated entry to CHANGELOG.md
- Update README.md if the change affects installation, usage, feature list, or pattern count
- - The pattern count lives in **one** place — the README "74 pattern categories" bullet — and is derived from SKILL.md's detection `###` entries. Don't restate it elsewhere; CI (`scripts/check-pattern-count.sh`) fails the build if the README number drifts from SKILL.md, so just add the new `###` entry and bump the README bullet.
+ - The pattern count lives in **one** place — the README "74 pattern categories" bullet — and is derived from references/patterns.md's detection `###` entries. Don't restate it elsewhere; CI (`scripts/check-pattern-count.sh`) fails the build if the README number drifts from references/patterns.md, so just add the new `###` entry and bump the README bullet.
## Architecture of the skill
The skill has three modes (`rewrite` default, `detect` flag-only, `edit` in-place) and processes text through this pipeline:
1. **Context profile detection** — auto-detects or accepts a profile hint (linkedin, blog, technical-blog, investor-email, docs, casual) that adjusts rule strictness via the tolerance matrix
- 2. **Pattern matching** — detection categories across content, language, structure, communication, and meta patterns (see SKILL.md for the catalog; the count is in the README bullet)
+ 2. **Pattern matching** — detection categories across content, language, structure, communication, and meta patterns (see references/patterns.md for the catalog; the count is in the README bullet)
3. **Vocabulary flagging** — 3-tier system: Tier 1 (always flag), Tier 2 (flag in clusters), Tier 3 (flag at high density)
4. **Severity classification** — P0 (credibility killers), P1 (obvious AI smell), P2 (stylistic polish)
5. **Output** — rewrite mode: 4 sections including a second-pass audit; detect mode: 2 sections with problem vs. judgment-call assessment
## Key constraints
- - The skill must remain a single `SKILL.md` file with agentskills.io-compatible frontmatter
+ - Keep the entry SKILL.md under 500 lines with agentskills.io-compatible frontmatter; preserve all rule text in the reference and generated artifacts.
+ - Run `bash scripts/sync-plugin-skill.sh && bash scripts/sync-cursor-rules.sh` after canonical edits. Never edit generated copies.
- Word replacement table entries need specific alternatives, not just "rephrase"
- The self-reference escape hatch (quoted examples exempt from flagging) must be preserved — without it the skill flags its own documentation
- Technical-blog profile has explicit word table exceptions (e.g., "robust" and "ecosystem" are legitimate in technical contexts)
- "Extra strict" and "skip" in the tolerance matrix have specific meanings defined in the file
- The `ai-writing-skill-field-guide` survey ranks this repo first on upkeep, and its author filed #12 here. Any public citation of that ranking has to carry the disclosure with it
## Compatibility
The skill works with Claude Code, OpenClaw/ClawHub, and any agentskills.io-compatible agent. The frontmatter includes both `agentskills_spec` and `openclaw` fields. Changes must not break either format.