| name | style-review |
| type | workflow |
| description | Reviews Markdown prose against the pinned agent-style v0.3.5 rules and optionally writes a polished copy beside the source. Use for specs, ADRs, PR bodies, release notes, and technical docs when prose quality or evidence discipline matters. |
| argument-hint | [file.md | before.md after.md] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write, Bash |
| effort | 3 |
| context | main |
| agent | technical-writer |
| when_to_use | Use as an opt-in REVIEW or SHIP gate for important prose artifacts. Do not use for every response, source code, casual chat, or non-English prose unless the user asks for style review. |
Style Review
Opt-in prose review for SDD artifacts using the portable agent-style v0.3.5
skill bundle. This skill is a second-pass review gate, not a global writing
mode. It does not edit AGENTS.md, CLAUDE.md, or any source document in
place.
Source and Scope
- Rule pack:
.claude/skills/agent-style/references/RULES.md
- Upstream note:
.claude/skills/agent-style/references/UPSTREAM.md
- Attribution:
.claude/skills/agent-style/references/NOTICE.md
- Detector reference:
.claude/skills/agent-style/references/rule-detectors.md
- Revision prompt:
.claude/skills/agent-style/references/revision-prompt.md
Use this skill for English technical prose where clarity, evidence, and review
readability matter:
- Specs and design docs
- ADRs and decision records
- PR titles and descriptions
- Release notes and changelog entries
- Runbooks, postmortems, and technical documentation
Do not use this skill for routine chat, code, generated logs, or prose where the
user's requested voice intentionally overrides formal technical style.
Required CLI Check
Before any audit, check whether the CLI is available:
agent-style --version
If the command is missing, do not claim style review has run. Report this exact
fallback:
style-review not run: `agent-style` CLI is not on PATH. Install with `pip install agent-style` or `npm install -g agent-style`, then rerun `/style-review <file>`.
Do not install dependencies unless the user explicitly asks.
Single-File Workflow
Invocation:
/style-review FILE.md
-
Read FILE.md and confirm it is prose that fits this skill's scope.
-
Run the deterministic audit:
agent-style review --audit-only FILE.md
-
Add semantic judgment for rules the CLI marks as skipped because they need
host-model context: RULE-01, RULE-03, RULE-04, RULE-08, RULE-11, RULE-F, and
RULE-H. Use the bundled agent-style rules and detector reference as the
source of truth.
-
Report a compact scorecard with per-rule counts and the first few examples.
-
Ask the user before writing any revised copy:
Produce a polished draft at FILE.reviewed.md?
-
On yes, compose the revision using the vendored revision prompt and write
only FILE.reviewed.md. Never modify FILE.md.
-
Re-run the audit on FILE.reviewed.md.
-
Show before/after scorecard and a diff so the user can merge hunks manually.
A/B Compare Workflow
Invocation:
/style-review BEFORE.md AFTER.md
Run:
agent-style review --mechanical-only --compare BEFORE.md AFTER.md
Report the per-rule delta. Do not ask for polish and do not write files.
Polish Invariants
The polished draft must obey these hard constraints:
- No new facts, metrics, citations, links, code behavior, or claims.
- Preserve Markdown structure unless the structure is the violation.
- Preserve meaning and approximate length budget.
- Resolve only flagged style issues.
- Write beside the source as
FILE.reviewed.md.
- Never mutate or overwrite the source file.
If RULE-H flags unsupported claims, do not invent evidence. Keep the claim
flagged or ask the user for the missing source.
SDD Integration
- In REVIEW, use this skill when a prose artifact is important enough that
clarity or citation discipline affects review quality.
- In SHIP, use this skill before final PR bodies, release notes, or docs when
the user asks for polish or when the agent claims prose quality.
- In verification-before-completion, a style-quality claim requires fresh audit
evidence from this skill or a clear statement that style review was skipped.
Self-Verification
When asked "is style-review active?", reply:
style-review active: audit 21 rules from agent-style v0.3.5 (deterministic via CLI; semantic via host for RULE-01, 03, 04, 08, 11, F, H); workflow at .claude/skills/style-review/SKILL.md.
