agent-style: 21 Writing Rules That Load Into Your Coding Agent

The Problem agent-style Targets: LLM Prose Habits, Not Grammar

Most style tooling runs after the text exists. agent-style takes the opposite position: the rules are formatted for an agent to follow while it generates, which is why the README calls it a ruleset rather than a linter. The distinction matters because the failure modes it names are not spelling mistakes. They are the recurring shapes of machine-written English: a paragraph that opens with "Additionally", a list where a sentence would do, a claim with no citation behind it.

The ruleset splits into two groups of equal standing. RULE-01 through RULE-12 are distilled from Strunk & White, Orwell, Pinker, and Gopen & Swan, and each rule cites its source by chapter, section, or essay rule. RULE-A through RULE-I come from the author's own logs of AI output across papers, grant proposals, documentation and agent configs between 2022 and 2026. The README is explicit that the second group is not literature-backed, which is a more honest framing than most style guides manage.

Who is this for? The scope table answers directly. In scope: API docs, design docs, research papers, grant proposals, READMEs, runbooks, commit messages, error messages, technical blog posts, postmortems and issue reports. Out of scope: fiction, poetry, marketing copy, long-form narrative non-fiction, non-English prose, and any context where rhythm or affect matter more than precision. If you write release notes or design docs with an agent, you are the target user. If you write brand copy, you are not.

How the Rules Load Into Claude Code, Codex, Copilot, Cursor and Aider

The mechanism is prompt injection at the point of generation. The repository ships an agents/ directory alongside packages/, skills/ and enforcement/, which is the layout you would expect from a project that has to produce a different artifact for each host tool. The README describes the package as a drop-in for Claude Code, Codex, Copilot, Cursor and Aider, and there is an adapter-matrix.md at the top level that appears to track which host supports which integration path. The README does not reproduce that matrix, so the file itself is the place to confirm coverage.

Two rules carry a critical marker: RULE-01 (do not assume the reader shares your tacit knowledge) and RULE-H (support factual claims with citation or concrete evidence; do not be handwavy). The hero figure in docs/ highlights exactly these two, which suggests the author treats the citation rule as the one that separates usable drafts from confident-sounding ones.

There is an escape hatch, quoted from Orwell's sixth rule: break any of these rules sooner than say anything outright barbarous. That line is doing real work. A ruleset that forbids em dashes and transition words will produce stilted prose if applied without judgement, and the escape hatch is the author acknowledging it.

One design choice deserves scrutiny. The two rule groups are described as peer inputs with no priority annotation. Canonical rules distilled from four published authorities sit at the same level as patterns logged from observed output. That is defensible for an agent reading a flat list, but it means a rule like "use title case for headings" carries the same weight as "do not overstate claims relative to the evidence." You may want to reorder them for your own use.

Installing agent-style From PyPI or npm and Reviewing Your First Draft

The README badges point to two registries: PyPI and npm. Both packages are named agent-style. The repository also exposes a command, agent-style review, which the README references when describing how the bench pairs were scored. That command is the fastest way to see what the ruleset actually flags before you wire it into an agent.

Install from PyPI:

pip install agent-style

Or, if your toolchain is JavaScript-based, the same package name exists on npm:

npm install agent-style

Once installed, the review command takes a draft and reports rule violations. The README uses it to isolate the style delta in its bench pairs, which is the intended reading: you point it at text you already have and read the rule IDs it fires.

agent-style review

The README does not document the flags, output format or exit codes for this command, so treat the invocation above as the starting point and check the CLI help before scripting it. For agent integration, the practical path is to copy the ruleset from the agents/ or skills/ directory into whatever configuration file your host tool reads, since that is the directory the repository layout reserves for host-specific artifacts. The README does not spell out the per-host file names.

What the Bench Pairs Show, and What They Do Not

The README reports three before-and-after pairs from a v0.3.0 bench: a product description on Gemini 3 Flash going from 8 to 0 violations, a design-doc section on Claude Opus 4.7 going from 14 to 7, and a paper related-work section on Gemini 3 Flash going from 6 to 4. Each pair used the same prompt with independent generations, one with the ruleset loaded and one without.

Read those numbers carefully. The design-doc pair improves by half, not to zero. The related-work pair moves by two violations. Only the product description reaches zero, and the README itself notes that the displayed baseline snippet in that third pair stops before the third benchmark name to keep the panel to three sentences, and that the drafts are anchored to prompt-named benchmarks so the style delta is isolated from fabricated-citation noise. That is an unusual level of caveat for a project's own marketing figure, and it is worth crediting.

The README also states that the counts in the hero figure are the original v0.3.0 scoring and do not match the corrected scores reported elsewhere in the document. Two sets of numbers for the same runs is a documentation debt. If you are evaluating this for a team, read the corrected figures, not the figure caption.

What the bench does not show: any measurement on commit messages, error messages, runbooks or postmortems, which are all listed as in scope. Three document types is a narrow sample for a 21-rule set.

Where agent-style Is the Wrong Tool

The scope table is the honest answer here, and it is unusually direct about it. Fiction, poetry, marketing copy and long-form narrative non-fiction are out of scope. So is non-English prose, and so is any context where rhythm or affect matter more than precision. A ruleset that forbids em dashes as casual punctuation and discourages transition words is actively hostile to prose whose job is cadence.

The second limitation is structural. These rules govern style, not truth. RULE-H asks for citation or concrete evidence, but a rule cannot supply the evidence. An agent that follows RULE-H perfectly can still produce a fluent paragraph that cites nothing real, and the ruleset has no mechanism to detect that. The README's own note about isolating style delta from fabricated-citation noise in the bench is an admission of this boundary.

The third is that a flat 21-rule list is a lot of instruction to hold in a context window alongside your actual task. The README gives no guidance on trimming the set for a narrow use case, and no measurement of what happens when an agent is given 21 rules instead of 12. If your agent already struggles to follow a short system prompt, adding 21 constraints will not fix that.

agent-style Compared With Vale and textlint

The obvious alternative is a prose linter such as Vale or textlint, and the difference in approach is the whole point of this project. A linter reads finished text and reports violations. agent-style is loaded before generation so the rules shape the draft as it is written. The README states this distinction directly: the rules are formatted for agents to follow at generation time, not as a post-hoc linter.

That difference has practical consequences. A linter gives you a pass/fail gate you can run in CI, with stable output you can diff between commits. agent-style gives you a probabilistic influence on generation, which is harder to verify and impossible to enforce uniformly across models. The bench numbers in the README are a snapshot of that influence on three specific model and document combinations, not a guarantee.

The two approaches are not mutually exclusive, and the repository layout suggests the author knows it. There is an enforcement/ directory at the top level alongside packages/ and skills/, and a .markdownlint-cli2.jsonc config file in the repository root, which is a linter configuration. The README does not explain what enforcement/ contains or how it relates to the ruleset, so that directory is the first thing to open if you want to know whether agent-style can also run as a check rather than only as a prompt.

Maintenance, Licence and Upgrade Cost

The last push to the default branch was on 2026-09-04, roughly two weeks before this writing. Three releases landed in August 2026: v0.4.0 on 2026-08-12, v0.4.1 on 2026-08-13, and v0.4.2 on 2026-08-14. That is a fast patch cadence within a single week, followed by continued commits. The repository is not archived.

The upgrade cost is low in one sense and non-zero in another. The ruleset is text, so pulling a new version is cheap. But the rules are also prompt content, which means a change to a rule can shift your agent's output in ways you did not ask for. If you pin a version, you avoid that. The CHANGELOG.md and RELEASING.md files at the top level are where the author tracks what changed between releases, and the adapter-matrix.md is where host compatibility is tracked, assuming it is kept current.

Licensing needs care. The README badge reads CC BY 4.0 plus MIT, and the repository contains a LICENSES/ directory and a NOTICE.md file, which is the standard pattern for a dual-licensed project where prose and code carry different terms. The README source carries an SPDX identifier of CC-BY-4.0. The repository page itself does not report a licence. If you redistribute the ruleset inside a commercial product, read NOTICE.md and the LICENSES/ directory rather than the badge, and get your own advice on which terms attach to which files.

Editorial conclusion

Adopt agent-style if you generate technical prose with Claude Code, Codex, Copilot, Cursor or Aider and keep editing the same LLM habits out of drafts. Skip it for fiction, poetry, marketing copy or non-English prose, which the README lists as out of scope. Before wiring it into a pipeline, confirm which licence applies to the files you redistribute: the README badge says CC BY 4.0 plus MIT, and the repository carries a LICENSES/ directory and NOTICE.md, but the LICENSE field is not filled in on the repository page.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. yzhao062/agent-style on GitHub