From petems-prose
Review markdown prose in the current location against the 21 writing rules from yzhao062/agent-style. Use when the user asks to review, audit, or check docs/READMEs/blog posts for AI tells, robotic phrasing, telltale AI patterns, or wants a prose quality pass. Triggers on /ai-prose-review.
How this skill is triggered — by the user, by Claude, or both
Slash command
/petems-prose:ai-prose-reviewThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Based on the excellent writing-rules work by Yue Zhao (USC).
Based on the excellent writing-rules work by Yue Zhao (USC). Original: https://github.com/yzhao062/agent-style This is my own simpler personal version of those rules, trimmed to a single-file review skill I can run on demand.
Audit markdown files in the current location against a checklist of 21 rules drawn from style authorities (Strunk & White, Orwell, Pinker, Gopen & Swan) and field-observed AI-tell patterns. Report violations first; only edit files after the user confirms.
/ai-prose-review (with or without a path argument).Skip this skill for fiction, poetry, marketing copy, or narrative writing where rhythm and affect matter more than precision. The rules below target technical prose: API docs, design docs, READMEs, runbooks, commit messages, blog posts.
target argument, use it directly. A path means that one file. A glob means expand it.**/*.md and **/*.mdx from the current working directory.node_modules/, .git/, vendor/, dist/, build/, .next/, .venv/.Use Glob for discovery. Use Read for each file.
For every file, read the full contents and check each of the 21 rules in the checklist below. Skip:
```).--- lines).For every violation, record: file path, line number, rule ID, the offending excerpt (short), and a one-sentence "why" so the user can decide whether to fix.
Group by file, ordered by severity. Use a compact table per file:
## docs/architecture.md (7 violations)
| Line | Rule | Severity | Excerpt | Why |
|------|---------|----------|----------------------------------------|--------------------------------------|
| 14 | RULE-H | High | "studies show that..." | Unsupported claim, no citation |
| 22 | RULE-12 | Medium | 38-word sentence starting "The system" | Over the 30-word ceiling; split it |
| 31 | RULE-D | Low | "Furthermore," (3rd para in a row) | Transition-word opener overused |
After the per-file tables, give a one-line summary: total files, total violations, breakdown by severity.
Stop after the report. Ask the user which violations to fix:
Do not pre-emptively rewrite anything.
If the user confirms, work one file at a time. Use Edit for each violation. Show the diff. For sentence-level rewrites (RULE-12 splits, RULE-02 voice changes), keep the rewrite minimal — preserve the author's voice and meaning. Do not introduce new content or change the technical claims.
After fixes, offer to re-run the review on the changed files to confirm violations are resolved.
Each rule lists a short name, a "spot it by" cue, a "fix by" cue, and severity.
Source: Strunk & White, Orwell, Pinker, Gopen & Swan.
Source: AI-tell patterns logged across LLM output 2022–2026.
— or – as a generic connector multiple times per paragraph. Fix: use a comma, semicolon, or full stop. Reserve dashes for genuine parenthetical breaks. Low.If the user asks for a quick pass, run only High and Medium.
<!-- ai-prose-review: skip --> to the next blank line.If the document is fiction, marketing copy, or narrative writing, stop and confirm with the user before reviewing. The rules target technical prose and will produce noisy results elsewhere.
When reporting, follow this shape:
# AI Prose Review
Reviewed N files. Found X violations: H high · M medium · L low.
## path/to/file-1.md (V violations)
| Line | Rule | Severity | Excerpt | Why |
|------|---------|----------|---------|-----|
| ... | ... | ... | ... | ... |
## path/to/file-2.md (V violations)
...
---
Which would you like to fix?
- All violations
- A specific file
- A specific rule (or just High severity)
- None — report only
Keep excerpts short (under ~80 chars). Truncate with … if needed. Always include the line number so the user can jump to the source.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub petems/ai-prose-review-skill --plugin petems-prose