[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1015":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":35,"discoverSource":36},1015,"agent-style","yzhao062\u002Fagent-style","yzhao062","21 writing rules for AI coding and writing agents. Drop-in for Claude Code, Codex, Copilot, Cursor, and Aider, so their output reads like a tech pro.","",null,"Python",493,25,1,2,0,7,16,61,21,4.24,false,"main",true,[26,27,28,29,30,31],"ai-agents","llm","prompt-engineering","style-guide","technical-writing","writing-style","2026-06-12 02:00:22","\u003C!-- SPDX-License-Identifier: CC-BY-4.0 -->\n\n\u003Ca id=\"readme-top\">\u003C\u002Fa>\n\n\u003Cdiv align=\"center\">\n\n# The Elements of Agent Style\n\n**Make your AI agent write like a tech pro.**\n\n*21 rules: 12 from classic writing guides, 9 from field observation of LLM output, 2022-2026.*\n\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fagent-style.svg?color=blue&cacheSeconds=300)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fagent-style\u002F)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fagent-style.svg?color=blue&cacheSeconds=300)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fagent-style)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-CC%20BY%204.0%20%2B%20MIT-blue.svg)](NOTICE.md)\n[![CI](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fagent-style\u002Factions\u002Fworkflows\u002Fvalidate.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fagent-style\u002Factions\u002Fworkflows\u002Fvalidate.yml)\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fyzhao062\u002Fagent-style?style=social&cacheSeconds=300)](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fagent-style)\n\n[Before \u002F after](#before-and-after)  · \n[What it is](#what-it-is)  · \n[Does it work?](#does-it-work)  · \n[Use](#use)\n\n\u003C\u002Fdiv>\n\n## Before and After\n\n![agent-style hero: 21 rules, then three real v0.3.0 bench before\u002Fafter pairs (product description, design-doc section, paper related-work section) with rule violations highlighted in the AI drafts and concrete details highlighted in the agent-style-loaded revisions](docs\u002Fhero.png)\n\nThe 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): 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.\n\n## What It Is\n\nA curated set of English writing rules formatted for AI coding and writing agents to follow **at generation time**, not as a post-hoc linter.\n\n### Scope\n\n| In scope | Out of scope |\n| --- | --- |\n| API docs, design docs, research papers, grant proposals | Fiction, poetry, marketing copy |\n| READMEs, runbooks, commit messages, error messages | Long-form narrative non-fiction |\n| Technical blog posts, postmortems, issue reports | Non-English prose; any context where rhythm or affect matter more than precision |\n\n### Two Rule Groups, Peer Inputs\n\nThe 21 rules split by origin. The agent reads both as equal peers; no group is annotated as higher-priority than the other.\n\n- **`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.\n- **`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.\n\nNamed in homage to Strunk & White's *The Elements of Style* (1918\u002F1959), one of the four canonical sources.\n\n### Canonical Rules (RULE-01 through RULE-12)\n\n![Four writing authorities cited by RULE-01..12: Strunk & White (Elements of Style, 1959), Orwell (Politics and the English Language, 1946), Pinker (Sense of Style, 2014), Gopen & Swan (Science of Scientific Writing, 1990), with the rule IDs distilled from each](docs\u002Fsources.png)\n\nSourced from writing authorities; each rule cites its source by chapter, section, or essay rule.\n\n| # | Rule | Primary source |\n| --- | --- | --- |\n| 01 | Do not assume the reader shares your tacit knowledge | Pinker 2014, Ch. 3 |\n| 02 | Do not use passive voice when the agent matters | Orwell 1946 Rule 3; S&W §II.14 |\n| 03 | Do not use abstract or general language when a concrete, specific term exists | S&W §II.16; Pinker 2014 Ch. 3 |\n| 04 | Do not include needless words | S&W §II.17; Orwell 1946 Rule 3 |\n| 05 | Do not use dying metaphors or prefabricated phrases | Orwell 1946 Rule 1 |\n| 06 | Do not use avoidable jargon where an everyday English word exists | Orwell 1946 Rule 5; Pinker 2014 Ch. 2 |\n| 07 | Use affirmative form for affirmative claims | S&W §II.15 |\n| 08 | Do not linguistically overstate or understate claims relative to the evidence | Pinker 2014 Ch. 6; Gopen & Swan 1990 |\n| 09 | Express coordinate ideas in similar form (parallel structure) | S&W §II.19 |\n| 10 | Keep related words together | S&W §II.20; Gopen & Swan 1990 |\n| 11 | Place new or important information in the stress position at the end of the sentence | Gopen & Swan 1990 |\n| 12 | Break long sentences; vary length (split sentences over 30 words) | S&W §II.18; Pinker 2014 Ch. 4 |\n\n### Field-Observed Rules (RULE-A through RULE-I)\n\nStructural 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.\n\n| # | Rule |\n| --- | --- |\n| A | Do not convert prose into bullet points unless the content is a genuine list (and do not over-bullet where 2 items or a sentence fit) |\n| B | Do not use em or en dashes as casual sentence punctuation |\n| C | Do not start consecutive sentences with the same word or phrase |\n| D | Do not overuse transition words (\"Additionally\", \"Furthermore\", \"Moreover\") |\n| E | Do not close every paragraph with a summary sentence |\n| F | Use consistent terms; do not redefine abbreviations mid-document |\n| G | Use title case for section and subsection headings (articles, short prepositions, and coordinating conjunctions stay lowercase) |\n| H | **Support factual claims with citation or concrete evidence; do not be handwavy (critical)** |\n| I | Prefer full forms over contractions in formal technical prose (\"it is\" over \"it's\") |\n\n**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.\n\nSee [`RULES.md`](RULES.md) for the full per-rule blocks with BAD\u002FGOOD examples, enforcement tier, and rationale.\n\n## Does It Work?\n\n![agent-style v0.3.0 sanity bench across Claude Opus 4.7, OpenAI GPT-5.4 via Codex CLI, and Gemini 3 Flash: 105 to 58 (-45%), 51 to 28 (-45%), and 79 to 14 (-82%) AI-tell violations across 10 fixed prose tasks, per-rule breakdown, directional-not-statsig caveat](docs\u002Fbench.png)\n\nSanity bench on 10 fixed prose tasks (2 PR descriptions, 1 design-doc section, 1 commit message, 4 paper sections, 1 product description, 1 NSF-style specific aim), 2 generations per condition, flagship models drafting with `agent-style` loaded at generation time vs not. Three models shown: **Claude Opus 4.7 dropped 45% (105 → 58 violations); OpenAI GPT-5.4 via Codex CLI dropped 45% (51 → 28); Gemini 3 Flash dropped 82% (79 → 14).** The GitHub Copilot CLI runner was tested but excluded from the figure because its `-p` programmatic mode does not load instruction files (+3% noise; see [`CHANGELOG.md`](CHANGELOG.md) Notes). See [`docs\u002Fbench-0.3.0.md`](docs\u002Fbench-0.3.0.md) for the full scorecard across all 4 runners plus per-runner drafts under [`docs\u002Fbench-0.3.0-drafts\u002F`](docs\u002Fbench-0.3.0-drafts\u002F), and [`RELEASING.md`](RELEASING.md) \"Bench (Local Only)\" for reproduction steps.\n\nNumbers are directional, not statsig: 10 tasks × 2 generations × 2 conditions = 40 calls per runner. The takeaway is that the ruleset reduces mechanical AI-tell density across every frontier family where the instruction file actually reaches the model's context; the exact size of the drop varies with each model's baseline (heavier in models that emit more long sentences \u002F em-dashes by default, smaller or zero in already-clean models).\n\n## Who It Is For\n\n- **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.\n- **Maintainers of those agents' configurations** who want generated prose to follow literature-backed writing conventions rather than reproduce common LLM tell-patterns.\n\n## Use\n\nTwo ways to enforce the rules in your AI agent's output. You typically use both:\n\n- **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.\n- **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.\n\nInstall the CLI once; then pick the paths you want.\n\n```bash\npip install agent-style                              # Python users\n# or: npm install -g agent-style                     # Node users\n# or: npx --yes agent-style@0.3.5 \u003Csubcommand>       # no install needed\n```\n\n### 1. Soft Enforcement — rules at generation time\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Set up via AI Agent\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nOnce the CLI is installed (per the install block above), paste the block below into your AI agent — it picks the right adapter, runs `enable`, verifies, and offers `style-review` if your host supports skills. Works with any AI agent that can run shell commands: Claude Code, Codex, Cursor, Aider, Kiro, GitHub Copilot, etc.\n\n```text\nSet up agent-style in this project. Steps:\n\n(If `agent-style` is not on PATH, substitute `npx --yes agent-style`\nfor `agent-style` in every command below.)\n\n1. Pick the adapter. Check more specific signals before broader\n   directory signals, and when more than one row fits, ask me which\n   host I want to configure.\n\n   | Signal in project or requested host                                | Adapter           |\n   | ------------------------------------------------------------------ | ----------------- |\n   | `.claude\u002Fskills\u002F` (Anthropic Skills host)                          | `anthropic-skill` |\n   | `CLAUDE.md` or `.claude\u002F` (Claude Code)                            | `claude-code`     |\n   | `AGENTS.md` (Codex CLI, Jules, Zed, Warp, Gemini CLI, VS Code, ...) | `agents-md`       |\n   | Codex API (manual system-prompt paste, no CLI host)                | `codex`           |\n   | `.github\u002Fcopilot-instructions.md`                                  | `copilot`         |\n   | `.github\u002Finstructions\u002F`                                            | `copilot-path`    |\n   | `.cursor\u002F`                                                         | `cursor`          |\n   | `.aider.conf.yml`                                                  | `aider`           |\n   | `.kiro\u002F`                                                           | `kiro`            |\n   | (none of the above)                                                | run `agent-style list-tools` and ask me which to use |\n\n2. Run `agent-style enable \u003Cadapter> --dry-run --json` first. Check the\n   `actions` array, then run the real `agent-style enable \u003Cadapter>`\n   and confirm each listed path was created.\n\n3. If the JSON has `manual_step_required: true` (Codex API, Aider),\n   surface the CLI's printed `manual step required:` line to me\n   verbatim. Do not claim setup is complete on my behalf.\n\n4. If any of `CLAUDE.md` \u002F `.claude\u002F` \u002F `.claude\u002Fskills\u002F` exists in\n   this project (skill-capable host available), also offer to run\n   `agent-style enable style-review` for the opt-in second-pass\n   review skill alongside soft enforcement.\n\n5. Report the adapter name and the created paths, then tell me to\n   restart my agent session and ask \"Is agent-style active?\".\n```\n\n\u003C\u002Fdetails>\n\nOr run it yourself:\n\n```bash\nagent-style enable claude-code                       # wire up Claude Code\n# Inside a Claude Code session, your prose now follows agent-style's 21 rules.\n```\n\nOther tools work the same way — substitute the tool name:\n\n```bash\nagent-style list-tools                               # see all supported tools\nagent-style enable agents-md                         # Codex, Jules, Zed, Warp, Gemini CLI, VS Code, others\nagent-style enable cursor                            # Cursor\nagent-style enable copilot                           # GitHub Copilot (repo-wide)\n# ...\nagent-style disable \u003Ctool>                           # reverse an enable\n```\n\n**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.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>What \u003Ccode>enable\u003C\u002Fcode> Does per Tool (All Safe, All Idempotent)\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\n- **Claude Code (`import-marker`)**: writes `.agent-style\u002FRULES.md` and `.agent-style\u002Fclaude-code.md`; safe-appends `@.agent-style\u002Fclaude-code.md` in a marker block to your existing `CLAUDE.md`. Creates `CLAUDE.md` only if absent.\n- **AGENTS.md, Copilot repo-wide (`append-block`)**: safe-appends a marker-wrapped compact adapter block to your existing instruction file. Content above and below the marker is preserved.\n- **Cursor, Copilot path-scoped, Anthropic Skills (`owned-file`)**: writes a new agent-style-owned file at the tool's rule-directory path (`.cursor\u002Frules\u002Fagent-style.mdc`, `.github\u002Finstructions\u002Fagent-style.instructions.md`, `.claude\u002Fskills\u002Fagent-style\u002FSKILL.md`). Fails closed if a non-agent-style file is already there.\n- **Codex API (`print-only`)**: writes `.agent-style\u002Fcodex-system-prompt.md`; prints the prompt body to stdout, manual-step instructions to stderr. You paste the prompt into your Codex API `system_prompt`.\n- **Aider (`multi-file-required`)**: writes `.agent-style\u002Faider-conventions.md`; prints a `.aider.conf.yml` snippet to stderr. You paste both files into the config.\n- **Kiro (`owned-file`)**: writes `.kiro\u002Fsteering\u002Fagent-style.md` as an auto-included steering file. Kiro loads it at session start for every interaction in the workspace.\n\nFor `print-only` and `multi-file-required`, the JSON output carries `manual_step_required: true` and `enabled: false`; exit code stays 0 (the CLI did everything it can do) and the first line of human output is exactly `manual step required:` followed by the specific action.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Per-surface install table (v0.3.5 primary set)\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\n| Tool | install_mode | Target path |\n| --- | --- | --- |\n| Claude Code | `import-marker` | `CLAUDE.md` (marker block with `@.agent-style\u002Fclaude-code.md`) |\n| AGENTS.md (Codex, Jules, Zed, Warp, Gemini CLI, VS Code, and others) | `append-block` | `AGENTS.md` at repo root |\n| GitHub Copilot (repo-wide) | `append-block` | `.github\u002Fcopilot-instructions.md` |\n| GitHub Copilot (path-scoped) | `owned-file` | `.github\u002Finstructions\u002Fagent-style.instructions.md` |\n| Cursor | `owned-file` | `.cursor\u002Frules\u002Fagent-style.mdc` |\n| Anthropic Skills | `owned-file` | `.claude\u002Fskills\u002Fagent-style\u002FSKILL.md` |\n| Codex (API \u002F manual paste) | `print-only` | `.agent-style\u002Fcodex-system-prompt.md` (user pastes into API system prompt) |\n| Aider | `multi-file-required` | `.agent-style\u002Faider-conventions.md` + `.aider.conf.yml` snippet |\n| Kiro (AWS IDE) | `owned-file` | `.kiro\u002Fsteering\u002Fagent-style.md` |\n| **style-review** (skill) | `skill-with-references` | `.claude\u002Fskills\u002Fstyle-review\u002FSKILL.md` + `.agent-style\u002Fskills\u002Fstyle-review\u002Freferences\u002F` |\n\nAmazon Q Developer, JetBrains AI Assistant, Windsurf, Ollama, Replit, OpenCode, Continue.dev, Tabnine, OpenAI Agents SDK skills, and Copilot path-scoped variants beyond the above are planned for v1.1; see the \"Planned adapters\" section of [`adapter-matrix.md`](adapter-matrix.md).\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>No-install path: pinned \u003Ccode>curl\u003C\u002Fcode> recipe\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nSkip the package install; pin to a specific release so adapters and `RULES.md` stay consistent:\n\n```bash\nAGENT_STYLE_REF=v0.3.5\nmkdir -p .agent-style\ncurl -fsSLo .agent-style\u002FRULES.md       \"https:\u002F\u002Fraw.githubusercontent.com\u002Fyzhao062\u002Fagent-style\u002F${AGENT_STYLE_REF}\u002FRULES.md\"\ncurl -fsSLo .agent-style\u002Fclaude-code.md \"https:\u002F\u002Fraw.githubusercontent.com\u002Fyzhao062\u002Fagent-style\u002F${AGENT_STYLE_REF}\u002Fagents\u002Fclaude-code.md\"\n```\n\nThen add ONE line to your `CLAUDE.md` (create the file only if absent; never overwrite):\n\n```text\n@.agent-style\u002Fclaude-code.md\n```\n\nFor other surfaces, substitute the adapter filename. The `curl` commands only write under `.agent-style\u002F`; the one-line import is the only edit you make to files you own.\n\n\u003C\u002Fdetails>\n\n### 2. Skill — `style-review` (opt-in second pass)\n\nTwo ways to use it depending on whether you have a skill-capable host:\n\n```bash\n# Skill-host path (Claude Code \u002F Anthropic Skills): install once, then \u002Fstyle-review \u003Cfile>\nagent-style enable style-review                       # auto-detects active skill-capable surfaces\n# inside Claude Code:\n\u002Fstyle-review DESIGN.md\n\n# CLI path (works anywhere pip\u002Fnpm runs; no skill host needed):\nagent-style review DESIGN.md                          # human-readable audit\nagent-style review DESIGN.md --audit-only             # machine-readable JSON\nagent-style review --compare a.md b.md                # A\u002FB delta per rule\n```\n\n**What happens on `\u002Fstyle-review DESIGN.md`** (skill path):\n\n1. Deterministic audit of the file against all 21 rules.\n2. Skill asks: *\"produce a polished draft at `DESIGN.reviewed.md`?\"*\n3. On yes: writes a revised copy beside the original and shows the diff. **Source file is never touched.**\n\n**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.\n\nSee the [Does It Work?](#does-it-work) section above for measured mechanical-violation reductions on Claude Opus 4.7 and OpenAI GPT-5.4.\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Skill workflow in detail (what the SKILL.md tells Claude Code to do)\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\n1. Shells out to `agent-style review --audit-only DESIGN.md` for the deterministic audit (same JSON as the CLI path).\n2. Adds semantic judgment via the host model for the 7 rules that need context-aware reasoning: RULE-01 curse of knowledge, RULE-03 vague language, RULE-04 needless words, RULE-08 uncalibrated claims, RULE-11 stress position, RULE-F term drift, RULE-H citation discipline.\n3. Merges deterministic + semantic scorecard; reports per-rule counts and first 5 violations each.\n4. Asks the user: *\"produce a polished draft at DESIGN.reviewed.md?\"*\n5. On yes, composes a revision prompt using `references\u002Frevision-prompt.md` with hard invariants:\n   - **No new facts, metrics, citations, links, or code behavior** not in the source.\n   - Preserve Markdown structure (code fences, tables, frontmatter, links, heading levels, list nesting).\n   - Preserve meaning and length budget.\n6. Writes `DESIGN.reviewed.md` alongside `DESIGN.md`.\n7. Re-audits the revised draft; shows before → after scorecard and `diff DESIGN.md DESIGN.reviewed.md`.\n\nSource file is never touched. You merge hunks from the `.reviewed.md` by hand.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Uninstall\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nPer-tool disable:\n\n```bash\nagent-style disable claude-code                       # or any other tool you enabled\nagent-style disable style-review                      # manifest-based safe removal\n```\n\nFor `style-review`, disable reads `.agent-style\u002Fskills\u002Fstyle-review\u002Fmanifest.json`, removes only files whose current sha256 still matches (leaves user-edited files alone and reports them as `drifted`), and cleans up empty directories. Never touches `.agent-style\u002FRULES.md` or other-tool adapters.\n\nFull cleanup of the shared `.agent-style\u002F` data (after disabling every tool you enabled):\n\n```bash\nrm -rf .agent-style\u002F                                   # POSIX\nRemove-Item -Recurse -Force .agent-style               # PowerShell\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Self-verification probe\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nAfter running `agent-style enable \u003Ctool>`, ask your agent:\n\n> Is agent-style active?\n\nExpected reply:\n\n> agent-style v0.3.5 active: 21 rules (RULE-01..12 canonical + RULE-A..I field-observed); full bodies at .agent-style\u002FRULES.md.\n\nFor `style-review` specifically, ask:\n\n> Is style-review active?\n\nExpected reply:\n\n> style-review active: audit 21 rules (deterministic: RULE-B, D, G, I, 12, 05, 06, A, C, E; semantic via host: RULE-01, 03, 04, 08, 11, F, H); workflow at skills\u002Fstyle-review\u002FSKILL.md.\n\nIf the version string or rule count is missing, the file is on disk but not in your agent's active context. Check that your tool's instruction-file reload behavior picked up the new content (some tools require a session restart).\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Complementary Post-Hoc Linting\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nThis repo is read at generation time. For a linter that runs over committed prose in CI, see [ProseLint](https:\u002F\u002Fgithub.com\u002Famperser\u002Fproselint); per-rule check-ID mappings are in [`enforcement\u002Fproselint-map.md`](enforcement\u002Fproselint-map.md). Vale users can plug ProseLint via its existing style-pack ecosystem.\n\n\u003C\u002Fdetails>\n\n### 3. Bundled via [anywhere-agents](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fanywhere-agents) (zero-config)\n\nIf your project already uses [`anywhere-agents`](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fanywhere-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.\n\n```bash\npipx run anywhere-agents   # Python path\nnpx anywhere-agents        # Node.js path\n```\n\nOpt 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: \u003Ctag>`. See [anywhere-agents rule-pack composition docs](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fanywhere-agents\u002Fblob\u002Fmain\u002Fdocs\u002Frule-pack-composition.md) for the full contract.\n\n### v0.3.0 Roadmap\n\nPlanned CLI additions: `agent-style update` (refresh installed adapters to latest), `agent-style override \u003CRULE-ID> disable` (per-rule opt-out), `agent-style clean` (one-command uninstall), `.agent-style\u002Fconfig.toml` (project-level config), RULE-02 \u002F 07 \u002F 09 \u002F 10 structural detectors filled in, and filled adapters for the planned-adapter set above (v1.1). Track progress in [`CHANGELOG.md`](CHANGELOG.md).\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Curation and method\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nThe 12 canonical rules are not a generated digest of the four source works. I read each source, extracted the rules most applicable to English technical prose, filtered for AI-agent failure modes I had seen in practice, and phrased each rule using the negative-versus-positive split that Zhang et al. 2026 found empirically effective for coding-agent instructions. Rules that are supported by a source but that do not map to a concrete AI-R&D failure mode are excluded. The intersection is what this repo ships as the canonical set.\n\nThe 9 field-observed rules (`RULE-A` through `RULE-I`) come from my own observation of AI output across dozens of writing projects and code releases, 2022 to 2026. Each pattern appeared often enough across distinct projects to warrant a named rule. These rules are labeled transparently as field observations in `RULES.md` and sit next to the canonical rules in all adapter files.\n\nNew contributions are welcome. A canonical-track rule must cite a source from the writing-authority bucket or the agent-instruction-evidence bucket below, include BAD\u002FGOOD examples drawn from real technical-prose output, and include a rationale for why the rule matters specifically for AI-agent-generated prose. I curate field-observed rule additions to keep the list tight.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Canonical sources\u003C\u002Fb>\u003C\u002Fsummary>\n\u003Cbr>\n\nFour writing authorities for prose content, plus two recent empirical papers for rule format and phrasing. Every one of the 12 canonical rules cites its source explicitly; **I verified every citation against the original work, not scraped or summarized from search results.** When the final text disagrees with an authority, the disagreement is stated in the rule's rationale.\n\n#### Writing Authorities (Prose Content)\n\n1. **Strunk, W., Jr., & White, E. B. (1959).** *The Elements of Style* (revised from Strunk 1918). The Macmillan Company. Especially Part II, \"Elementary Principles of Composition\" (§§12-22).\n2. **Orwell, G. (1946).** \"Politics and the English Language.\" *Horizon*, April 1946. Public domain; freely available online.\n3. **Pinker, S. (2014).** *The Sense of Style: The Thinking Person's Guide to Writing in the 21st Century*. Viking. Especially Ch. 2 (classic style), Ch. 3 (curse of knowledge), Ch. 6 (calibrated claims).\n4. **Gopen, G. D., & Swan, J. A. (1990).** \"The Science of Scientific Writing.\" *American Scientist*, 78(6), pp. 550-558.\n\n#### Agent-Instruction Evidence (Rule Format and Phrasing)\n\n5. **Zhang, X. et al. (2026).** \"Do Agent Rules Shape or Distort? Guardrails Beat Guidance in Coding Agents.\" arXiv:2604.11088. 25,532 rules across 679 instruction files; motivates negative-constraint phrasing for anti-pattern rules.\n6. **Bohr, J. (2025).** \"Show and Tell: Prompt Strategies for Style Control in Multi-Turn LLM Code Generation.\" arXiv:2511.13972. Motivates the directive + BAD\u002FGOOD example format used throughout `RULES.md`.\n\nSee [`SOURCES.md`](SOURCES.md) for the full bibliography and recommended reading ranges per source.\n\n\u003C\u002Fdetails>\n\n## License\n\nDual license with file-level SPDX boundaries:\n\n| Content | License |\n| --- | --- |\n| `RULES.md`, `SOURCES.md`, `NOTICE.md`, `agents\u002F`, `adapter-matrix.md` | [CC BY 4.0](LICENSES\u002FCC-BY-4.0.txt) |\n| `enforcement\u002F`, `.github\u002Fworkflows\u002F`, generator scripts | [MIT](LICENSES\u002FMIT.txt) |\n\nEvery source file carries an SPDX-License-Identifier header. See [`NOTICE.md`](NOTICE.md) for the attribution snippet consumers should retain on reuse.\n\n## Maintenance\n\nMaintained by [Yue Zhao](https:\u002F\u002Fyzhao062.github.io), USC CS faculty and author of [PyOD](https:\u002F\u002Fgithub.com\u002Fyzhao062\u002Fpyod). Issues and pull requests welcome; contributions that add a canonical rule must cite a source from the buckets above. See [`CHANGELOG.md`](CHANGELOG.md) for release history and upcoming work.\n\n\u003Cdiv align=\"center\">\n\n\u003Ca href=\"#readme-top\">↑ back to top\u003C\u002Fa>\n\n\u003C\u002Fdiv>\n","该项目旨在通过21条写作规则来提升AI编码和写作代理的输出质量，使其更符合技术专业人士的写作风格。它适用于Claude Code、Codex、Copilot等AI工具，以确保这些工具生成的内容更加专业和技术化。核心功能包括一套精心策划的英语写作规则集，专为在生成时被AI遵循而设计，而非事后检查。这些规则分为经典写作指南中的12条和从2022年至2026年期间对大语言模型输出观察得出的9条。此项目特别适合需要提高技术文档如API文档、设计文档、研究论文等质量的场景使用，同时也支持README文件、运行手册以及错误信息等技术性较强的文本创作。","2026-06-11 02:41:07","CREATED_QUERY"]