humanizer

What this skill does

# Humanizer: Remove AI Writing Patterns

You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.

## Audience classification

Before applying any humanizing rules, classify each input file as either `skill-file` or `prose`. The label selects which rule profile gets applied. Each rule heading below carries a `[profile: <value>]` tag (`both`, `prose`, or `skill-file`) that gates whether the rule fires for a given file. See `## Example-region exception` for the within-file carve-out that routes embedded examples back to the prose profile even inside a `skill-file`-classified input, and `### Applied-profile summary format` for how the per-file rule-application result is reported.

### Heuristics (first-match-wins, priority order)

Apply these heuristics in order. The first one that fires wins; later heuristics are not evaluated for that file.

1. **Filename match** — If the file is literally named `SKILL.md` (case-sensitive), classify as `skill-file`. This is the canonical Claude Code skill manifest filename. Example: `plugins/foo/skills/foo/SKILL.md` → `skill-file`. Example: `docs/SKILL.md` → `skill-file` (filename wins over the documentation-shaped path; the operator can `audience=prose` override for that rare case).

2. **YAML frontmatter shape** — Open the file. If its first non-empty content is a `---`-delimited YAML block containing *all three* of the keys `name:`, `description:`, and `allowed-tools:`, classify as `skill-file`. This is the canonical Claude Code skill manifest header; a file with this shape is a skill regardless of filename or extension. Example: `agents/my-helper.md` with frontmatter `name: my-helper`, `description: ...`, `allowed-tools: [...]` → `skill-file`.

3. **Path segment match** — Normalize path separators (replace `\` with `/`), split the path on `/`, and look for a *literal path component* match (not substring) of any of these patterns:
   - `skills/<name>/` — any skill within a plugin or repo
   - `.claude/skills/`
   - `.claude/agents/`
   - `plugins/<name>/skills/<name>/` — Claude Code plugin layout
   
   Component-aware matching is required: `myskills/foo/bar.md` must NOT classify as `skill-file` (no path component equals `skills`), while `lib/skills/foo/bar.md` WOULD (path component `skills` appears). Example: `.claude/skills/example/example.md` → `skill-file`. Example: `lib/agents/foo.md` → does NOT fire (path component `agents` without `.claude/` prefix is not in the list); falls through to heuristic 4.

4. **Sibling SKILL.md** — Two checks against the filesystem, in order:
   - **(a) Co-located.** If the file's immediate parent directory contains a `SKILL.md`, classify as `skill-file`. Example: `notes.md` next to `SKILL.md` in the same directory.
   - **(b) One-level companion.** If the file's immediate parent directory is named `references`, `scripts`, `tests`, or `examples`, walk up exactly one level and look for `SKILL.md` there. If present, classify as `skill-file`. Example: `vendor/foo/references/api.md` finds `vendor/foo/SKILL.md` and classifies as `skill-file`. The walk is bounded to one level; deeper nesting falls through.
   
   The companion-directory name list is empirical; extend it if real layouts surface other conventions. Layouts that already match heuristic 3 (`skills/<name>/`) will typically resolve via that earlier heuristic, but heuristic 4 still catches non-standard layouts (e.g., vendored skills under `vendor/<name>/`).

5. **Fallback** — No heuristic matched. Classify as `prose`.

The path-segment list in heuristic 3 is empirical, derived from observed Claude Code skill layouts. Downstream consumers that organize skills under non-standard paths (e.g., a bare `agents/` directory with no `.claude/` prefix) will fall through to heuristic 4 or the fallback. If a real layout consistently misses, extend the list rather than relaxing the matching rule.

### Raw-text input

When the humanizer is invoked on raw text pasted into the conversation (no file path), the classifier returns `prose` by default. There is no signal to evaluate. The operator can force the other label with `audience=skill-file`.

### The `audience=` argument

Operators can override classification by passing a global `audience=` token in `$ARGUMENTS`:

- `audience=skill-file` — force every file in this invocation to the skill-file profile, regardless of detection.
- `audience=prose` — force every file to the prose profile.
- `audience=auto` (default) — classify each file independently using the heuristics above.

Parse the argument inline from `$ARGUMENTS`: look for a single `audience=<value>` token. If absent, behave as `audience=auto`. The override is **global to the invocation** — there is no per-file override. If an operator needs to force one label for some files and a different label for others, they run humanizer twice.

### Per-file processing loop

When the invocation passes one or more file paths:

1. **Resolve the file list** from `$ARGUMENTS`. Strip the `audience=` token; the remaining tokens are file paths.
2. **For each file**, determine the audience:
   - If `audience=skill-file` or `audience=prose` is set, use that label (record as forced).
   - Otherwise, run the heuristics in order and record the resolved label.
3. **Process each file under the rule set selected by its label.** Files labeled `skill-file` apply rules tagged `[profile: skill-file]` or `[profile: both]`; files labeled `prose` apply rules tagged `[profile: prose]` or `[profile: both]`. Within a `skill-file`-classified file, apply the example-region exception (see `## Example-region exception`) so embedded examples are rewritten under the `prose` rule set.
4. **Accumulate the decisions** as you go — one row per file, recording path and label (and `(forced)` if forced).
5. **Emit the classification summary** at the end of the run (see format below).

Do not short-circuit on the first file. Process every file and report every decision so the operator can verify auto-detection landed correctly across the whole input.

### Classification summary format

After processing, emit a summary block in this exact shape:

```
Auto-detected audiences:
  plugins/humanizer/skills/humanizer/SKILL.md  -> skill-file
  plugins/humanizer/skills/humanizer/references/best-practices.md  -> skill-file
  CHANGELOG.md  -> prose
```

Indentation: two spaces. Separator: two spaces, the arrow `->`, one space, the label. No column alignment — paths vary too much in length and alignment would require a second pass.

When `audience=skill-file` or `audience=prose` is forced globally, append `(forced)` to each row so a reader can spot operator overrides at a glance:

```
Auto-detected audiences:
  plugins/humanizer/skills/humanizer/SKILL.md  -> skill-file (forced)
  CHANGELOG.md  -> skill-file (forced)
```

Prefer repo-relative paths when the input is repo-relative; pass absolute paths through unchanged if that is what the invocation supplied.

### Applied-profile summary format

After the `Auto-detected audiences:` block, emit an `Applied profiles:` block immediately following it (no blank line between is fine; the operator reads the two blocks as classification → consequence). The new block reports the resolved profile per file and a `(N rules applied, M skipped)` count so the operator can sanity-check the gating fired as expected.

Pinned shape:

```
Applied profiles:
  plugins/humanizer/skills/humanizer/SKILL.md  -> skill-file (18 rules applied, 7 skipped)
  CHANGELOG.md  -> prose (25 rules applied, 0 skipped)
```

Two-space indent. Separator: two spaces, the arrow `->`, one space, the resolved profile name. Parenthesized count. No column alignment — paths vary too much in length and alignment would require a second pass.

**Count semantics.** `applied` = numbered rules whose tag matches the active profile or i