yzhao062/agent-style

The Elements of Agent Style – What It Is

agent‑style is a small, language‑agnostic library (available on PyPI and npm) that ships a curated list of 21 writing rules for AI coding‑and‑writing agents. The rules combine classic style advice (Strunk & White, Orwell, Pinker, Gopen & Swan) with patterns the author observed in LLM‑generated prose between 2022‑2026. The idea is that an agent can read the rules at generation time – they become part of the system prompt – so the model tries to obey them while it writes the first draft, rather than fixing the text afterwards.

Scope of the Rules

In‑scope document types	Out‑of‑scope
API docs, design docs, research papers, grant proposals, READMEs, runbooks, commit messages, technical blog posts, post‑mortems, issue reports	Fiction, poetry, marketing copy, long‑form narrative non‑fiction, non‑English prose, prose where rhythm/affect matters more than precision

The 21 rules are split into two peer groups:

• RULE‑01 … 12 – canonical rules taken directly from the four classic style references, each with a precise citation.
• RULE‑A … I – “field‑observed” rules that capture recurring LLM‑specific slip‑ups (e.g., over‑use of bullet points, dashes, repeated sentence starts, unnecessary transition words, missing citations, etc.).

Both groups are treated equally; no rule is marked as higher priority.

How It Works

1. Soft enforcement (generation‑time) – You run agent-style enable <adapter> for the AI tool you use (Claude Code, GitHub Copilot, Cursor, Aider, etc.). The CLI writes a small rule file (or appends a marker block) into the location that the tool reads as part of its system prompt. When the model generates text, the rules are present in its context, nudging it toward the desired style.
2. Skill / second‑pass review – After a draft is produced you can run agent-style style-review <path> (or invoke the style‑review skill on a host that supports skills). The command audits the draft against the same 21 rules and, with your confirmation, writes a polished copy alongside the original.

The package ships adapters for many popular agents (Claude Code, Codex/AGENTS.md, GitHub Copilot, Cursor, Anthropic Skills, Kiro, etc.) and even a “no‑install” curl recipe that just pulls the rule files into a .agent-style folder.

Does It Help?

The author includes a sanity benchmark on ten fixed technical‑writing tasks (product description, design‑doc section, paper related‑work, PR description, commit message, etc.). For each task the models were run twice – once with the rules loaded and once without – and a mechanical‑only reviewer counted rule violations.

Model (2026)	Violations without rules	Violations with rules	Reduction
Claude Opus 4.7	88	47	‑47 %
OpenAI GPT‑5.4 (Codex CLI)	48	26	‑46 %
Gemini 3 Flash	65	9	‑86 %
GitHub Copilot (control)	52	52	0 %

The benchmark only measures a subset of the rules (seven mechanical ones) because the reviewer runs in “mechanical‑only” mode. The biggest gains come from reducing long sentences (RULE‑12), avoiding em/en dashes (RULE‑B), and cutting jargon (RULE‑06). Semantic rules such as citation discipline (RULE‑H) and “curse of knowledge” (RULE‑01) are not covered by the current bench, so the numbers are directional only and not a claim of statistical significance.

Who Might Use It

• Developers of AI coding or writing assistants (Claude Code, Codex, GitHub Copilot, Cursor, Aider, Kiro, Replit, etc.) who want their agents to produce clearer, more conventional technical prose.
• Maintainers of those agents who need a simple way to inject style guidance into the model’s prompt or to add a post‑generation review step.

Quick Start (Python example)

pip install agent-style          # or npm i -g agent-style
agent-style enable claude-code   # writes the rule files for Claude Code
# later, after a draft exists:
agent-style style-review path/to/file.md

The README also provides detailed tables of which files are created for each supported tool, a list of planned future adapters, and a full RULES.md with BAD/GOOD examples.

---

Bottom line: agent‑style is a practical, open‑source utility that lets you embed a concise, literature‑backed style guide into the prompt of any LLM‑based writing agent, and optionally run a lightweight rule‑based audit after generation. It targets the niche of improving the clarity and consistency of AI‑generated technical documentation rather than building new models or training pipelines.