yzhao062/agent-style

Before and After

The top row is the identity: 21 rules, 12 canonical plus 9 field-observed; bordered red marks the two critical rules (RULE-01 curse-of-knowledge and RULE-H citation discipline). The bottom three rows are the mechanism, each pulled from a real v0.3.0 bench draft pair (same prompt, independent generations with and without the ruleset). Their counts are the original v0.3.0 scoring, which the figure states, so they do not match the corrected scores reported under "Does It Work?" below. The rows are a product description on Gemini 3 Flash (8 → 0 violations), a design-doc section on Claude Opus 4.7 (14 → 7), and a paper related-work section on Gemini 3 Flash (6 → 4; the source drafts are anchored to three prompt-named benchmarks (AgentBench, BFCL, tau-bench) so the style delta measured by agent-style review is isolated from fabricated-citation noise, though the displayed baseline snippet stops before the third name to keep the panel to three sentences). Each row shows the AI draft on the left with rule-violating phrases highlighted, the specific rules that fire in the middle, and the revised version on the right at the same length budget, same register, same document type.

What It Is

A curated set of English writing rules formatted for AI coding and writing agents to follow at generation time, not as a post-hoc linter.

Scope

Two Rule Groups, Peer Inputs

The 21 rules split by origin. The agent reads both as equal peers; no group is annotated as higher-priority than the other.

• RULE-01..12 (canonical). Distilled from Strunk & White, Orwell, Pinker, and Gopen & Swan. Each rule cites its source by chapter, section, or essay rule; I verified every citation against the original works. Full names in the table below.
• RULE-A..I (field-observed). Patterns I logged from AI output across dozens of writing projects (papers, grant proposals, technical documentation, agent configs) and code releases, 2022 to 2026. Transparent attribution: these are not literature-backed but capture LLM-specific failure modes that the canonical set alone misses (RULE-H citation discipline is the critical one). Full names in the table below.

Named in homage to Strunk & White's The Elements of Style (1918/1959), one of the four canonical sources.

Canonical Rules (RULE-01 through RULE-12)

Sourced from writing authorities; each rule cites its source by chapter, section, or essay rule.

Field-Observed Rules (RULE-A through RULE-I)

Structural patterns logged from LLM output across research, proposal, documentation, and agent-configuration work, 2022 to 2026. Treated as peer input to the canonical rules when an agent consumes the ruleset.

Escape hatch (Orwell 1946 Rule 6): "Break any of these rules sooner than say anything outright barbarous." Rules are guides to clarity, not ends in themselves.

See RULES.md for the full per-rule blocks with BAD/GOOD examples, enforcement tier, and rationale.

Does It Work?

Sanity bench on 10 fixed prose tasks, 2 generations per condition. The task set is 2 PR descriptions, 1 design-doc section, 1 commit message, 4 paper sections, 1 product description, and 1 NSF-style specific aim. Flagship models drafted each one twice: once with agent-style loaded at generation time, once without.

Three models are eligible for a treatment comparison. Claude Opus 4.7 dropped 47% (88 → 47 violations). OpenAI GPT-5.4 via Codex CLI dropped 46% (48 → 26). Gemini 3 Flash dropped 86% (65 → 9). GitHub Copilot CLI reported no change at all (52 → 52). Treat that fourth number as a noise control, not a fourth treatment result. In the April 2026 setup, copilot -p showed no measurable effect from the installed instruction file. That archived result is specific to the version and setup of the day. Current Copilot CLI documentation describes repository instruction discovery, so it says nothing about present-day -p behavior.

What the bench measures, and what it does not

Scoring runs agent-style review --mechanical-only. These numbers therefore cover 7 of the 21 rules: RULE-05, 06, 12, B, D, G and I. That flag also disabled the structural detectors, so RULE-A, C and E contributed nothing, and the semantic rules need a model host the bench never ran.

Three of those seven carry almost all of the movement: sentence length (RULE-12), em and en dashes (RULE-B), and the jargon word list (RULE-06). Both the original and corrected pooled totals include the Copilot control alongside the three treatment-eligible arms. Under the original v0.3.0 scoring, those three account for a net 120 of the pooled 133-violation reduction, or 90%. The corrected scoring reported here gives 112 of 119 by the same calculation, or 94%. On the Codex arm, sentence length alone is the entire delta.

Both critical-severity rules are measured by nothing here. RULE-01 (curse of knowledge) and RULE-H (citation discipline) are semantic-only. No bench in this repository reports on the two rules the ruleset itself ranks highest. Read these percentages as mechanical AI-tell density on a Markdown surface. They are not evidence about argument quality, clarity for a stated audience, or sourcing.

Numbers are directional and carry no claim of statistical significance. Each runner saw 10 tasks × 2 generations × 2 conditions, or 40 calls. Where the instruction file reaches the model's context, mechanical AI-tell density falls. How far it falls tracks each model's baseline, and is larger in models that emit long sentences and em-dashes by default.

The figure above is scored with the v0.4.2 engine and comes from docs/bench-0.3.0-rescored.md. It re-scores the same 160 preserved drafts with the repaired detectors, reporting the original and corrected value side by side. Repairing divergences between a rule's directive and its detector moved the pooled delta from -133 to -119, most recently by teaching RULE-12 to see a sentence boundary through Markdown markup. That correction is small next to the scope limits above.

Original scorecards remain at docs/bench-0.3.0.md and the preserved drafts at docs/bench-0.3.0-drafts/. Reproduction steps live in RELEASING.md under "Bench (Local Only)". The figure now shows the corrected scoring, regenerated for this release. No new model generation was run: the same preserved drafts were re-scored.

Who It Is For

• AI coding and writing agents: Claude Code, Codex, GitHub Copilot, Cursor, Aider, Anthropic Skills, Kiro, Replit Agent, Windsurf, Amazon Q Developer, JetBrains AI Assistant, Ollama, Continue.dev, Tabnine, OpenCode, OpenAI Agents SDK skills, and any AGENTS.md-compliant tool. Each agent reads the ruleset as part of its system prompt or project config.
• Maintainers of those agents' configurations who want generated prose to follow literature-backed writing conventions rather than reproduce common LLM tell-patterns.

Use

Two ways to enforce the rules in your AI agent's output. You typically use both:

• 1. Soft enforcement (default): the rules are loaded at generation time, so the agent tries to follow them while writing the first draft. One enable command per tool; then the agent reads agent-style's 21 rules as part of its context.
• 2. Skill (opt-in second pass): after the draft exists, you ask for a review. style-review audits the draft against the same 21 rules and, on your confirmation, writes a polished copy beside the original. Your source file is never touched.

Install the CLI once; then pick the paths you want.

pip install agent-style                              # Python users
# or: npm install -g agent-style                     # Node users
# or: npx --yes [email protected] <subcommand>       # no install needed

1. Soft Enforcement — rules at generation time

Set up agent-style in this project. Steps:

(If `agent-style` is not on PATH, substitute `npx --yes agent-style`
for `agent-style` in every command below.)

1. Pick the adapter. Check more specific signals before broader
   directory signals, and when more than one row fits, ask me which
   host I want to configure.

   | Signal in project or requested host                                | Adapter           |
   | ------------------------------------------------------------------ | ----------------- |
   | `.claude/skills/` (Anthropic Skills host)                          | `anthropic-skill` |
   | `CLAUDE.md` or `.claude/` (Claude Code)                            | `claude-code`     |
   | `AGENTS.md` (Codex CLI, Jules, Zed, Warp, Gemini CLI, VS Code, ...) | `agents-md`       |
   | Codex API (manual system-prompt paste, no CLI host)                | `codex`           |
   | `.github/copilot-instructions.md`                                  | `copilot`         |
   | `.github/instructions/`                                            | `copilot-path`    |
   | `.cursor/`                                                         | `cursor`          |
   | `.aider.conf.yml`                                                  | `aider`           |
   | `.kiro/`                                                           | `kiro`            |
   | (none of the above)                                                | run `agent-style list-tools` and ask me which to use |

2. Run `agent-style enable <adapter> --dry-run --json` first. Check the
   `actions` array, then run the real `agent-style enable <adapter>`
   and confirm each listed path was created.

3. If the JSON has `manual_step_required: true` (Codex API, Aider),
   surface the CLI's printed `manual step required:` line to me
   verbatim. Do not claim setup is complete on my behalf.

4. If any of `CLAUDE.md` / `.claude/` / `.claude/skills/` exists in
   this project (skill-capable host available), also offer to run
   `agent-style enable style-review` for the opt-in second-pass
   review skill alongside soft enforcement.

5. Report the adapter name and the created paths, then tell me to
   restart my agent session and ask "Is agent-style active?".

Or run it yourself:

agent-style enable claude-code                       # wire up Claude Code
# Inside a Claude Code session, your prose now follows agent-style's 21 rules.

Other tools work the same way — substitute the tool name:

agent-style list-tools                               # see all supported tools
agent-style enable agents-md                         # Codex, Jules, Zed, Warp, Gemini CLI, VS Code, others
agent-style enable cursor                            # Cursor
agent-style enable copilot                           # GitHub Copilot (repo-wide)
# ...
agent-style disable <tool>                           # reverse an enable

Caveats: soft enforcement nudges the model. Training-prior vocabulary like leverages, cutting-edge, Additionally-openers, and closer sentences can still appear in the first draft, especially for prose over 200 words. That's why path 2 exists.

AGENT_STYLE_REF=v0.4.2
mkdir -p .agent-style
curl -fsSLo .agent-style/RULES.md       "https://raw.githubusercontent.com/yzhao062/agent-style/${AGENT_STYLE_REF}/RULES.md"
curl -fsSLo .agent-style/claude-code.md "https://raw.githubusercontent.com/yzhao062/agent-style/${AGENT_STYLE_REF}/agents/claude-code.md"

@.agent-style/claude-code.md

2. Skill — style-review (opt-in second pass)

Two ways to use it depending on whether you have a skill-capable host:

# Skill-host path (Claude Code / Anthropic Skills): install once, then /style-review <file>
agent-style enable style-review                       # auto-detects active skill-capable surfaces
# inside Claude Code:
/style-review DESIGN.md

# CLI path (works anywhere pip/npm runs; no skill host needed):
agent-style review DESIGN.md                          # human-readable audit
agent-style review DESIGN.md --audit-only             # machine-readable JSON
agent-style review --compare a.md b.md                # A/B delta per rule

What happens on /style-review DESIGN.md (skill path):

1. Deterministic audit of the file against all 21 rules.
2. Skill asks: "produce a polished draft at DESIGN.reviewed.md?"
3. On yes: writes a revised copy beside the original and shows the diff. Source file is never touched.

What you get from agent-style review DESIGN.md (CLI path): the same deterministic audit — mechanical + structural detectors for em-dashes, jargon, transition openers, clichés, contractions, sentence length, bullet overuse, same-starts, paragraph closers. Semantic rules (vague claims, unsupported claims, etc.) return status: "skipped" because they need a skill host's model. No polish from the plain CLI.

See the Does It Work? section above for measured mechanical-violation reductions on Claude Opus 4.7 and OpenAI GPT-5.4.

agent-style disable claude-code                       # or any other tool you enabled
agent-style disable style-review                      # manifest-based safe removal

rm -rf .agent-style/                                   # POSIX
Remove-Item -Recurse -Force .agent-style               # PowerShell

3. Bundled via anywhere-agents (zero-config)

If your project already uses anywhere-agents — a maintained agent configuration for Claude Code, Codex, and other AGENTS.md-compliant tools — agent-style is the default rule pack: no enable step needed. The anywhere-agents bootstrap fetches agent-style's canonical rules at a pinned git tag and composes them into your project's AGENTS.md automatically on every run.

pipx run anywhere-agents   # Python path
npx anywhere-agents        # Node.js path

Opt out by adding rule_packs: [] to agent-config.yaml at your project root; pin to a specific ref or swap for a fork via rule_packs: - name: agent-style\n ref: <tag>. See anywhere-agents rule-pack composition docs for the full contract.

v0.4.2+ Roadmap

Planned CLI additions: agent-style update (refresh installed adapters to latest), agent-style override <RULE-ID> disable (per-rule opt-out), agent-style clean (one-command uninstall), .agent-style/config.toml (project-level config), RULE-02 / 07 / 09 / 10 structural detectors filled in, and filled adapters for the planned-adapter set above (v1.1). Track progress in CHANGELOG.md.

License

Dual license with file-level SPDX boundaries:

Every source file carries an SPDX-License-Identifier header. See NOTICE.md for the attribution snippet consumers should retain on reuse.

Maintenance

Maintained by Yue Zhao, USC CS faculty and author of PyOD. Issues and pull requests welcome; contributions that add a canonical rule must cite a source from the buckets above. See CHANGELOG.md for release history and upcoming work.