The Elements of Agent Style

• Claude Code (import-marker): writes .agent-style/RULES.md and .agent-style/claude-code.md; safe-appends @.agent-style/claude-code.md in a marker block to your existing CLAUDE.md. Creates CLAUDE.md only if absent.
• 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.
• Cursor, Copilot path-scoped, Anthropic Skills (owned-file): writes a new agent-style-owned file at the tool's rule-directory path (.cursor/rules/agent-style.mdc, .github/instructions/agent-style.instructions.md, .claude/skills/agent-style/SKILL.md). Fails closed if a non-agent-style file is already there.
• Codex API (print-only): writes .agent-style/codex-system-prompt.md; prints the prompt body to stdout, manual-step instructions to stderr. You paste the prompt into your Codex API system_prompt.
• Aider (multi-file-required): writes .agent-style/aider-conventions.md; prints a .aider.conf.yml snippet to stderr. You paste both files into the config.
• Kiro (owned-file): writes .kiro/steering/agent-style.md as an auto-included steering file. Kiro loads it at session start for every interaction in the workspace.

For 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.

Amazon 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.

Skip the package install; pin to a specific release so adapters and RULES.md stay consistent:

AGENT_STYLE_REF=v0.3.1
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"

Then add ONE line to your CLAUDE.md (create the file only if absent; never overwrite):

@.agent-style/claude-code.md

For other surfaces, substitute the adapter filename. The curl commands only write under .agent-style/; the one-line import is the only edit you make to files you own.

1. Shells out to agent-style review --audit-only DESIGN.md for the deterministic audit (same JSON as the CLI path).
2. 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.
3. Merges deterministic + semantic scorecard; reports per-rule counts and first 5 violations each.
4. Asks the user: "produce a polished draft at DESIGN.reviewed.md?"
5. On yes, composes a revision prompt using references/revision-prompt.md with hard invariants:
   • No new facts, metrics, citations, links, or code behavior not in the source.
   • Preserve Markdown structure (code fences, tables, frontmatter, links, heading levels, list nesting).
   • Preserve meaning and length budget.
6. Writes DESIGN.reviewed.md alongside DESIGN.md.
7. Re-audits the revised draft; shows before → after scorecard and diff DESIGN.md DESIGN.reviewed.md.

Source file is never touched. You merge hunks from the .reviewed.md by hand.

Per-tool disable:

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

For style-review, disable reads .agent-style/skills/style-review/manifest.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/RULES.md or other-tool adapters.

Full cleanup of the shared .agent-style/ data (after disabling every tool you enabled):

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

After running agent-style enable <tool>, ask your agent:

Is agent-style active?

Expected reply:

agent-style v0.3.1 active: 21 rules (RULE-01..12 canonical + RULE-A..I field-observed); full bodies at .agent-style/RULES.md.

For style-review specifically, ask:

Is style-review active?

Expected reply:

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/style-review/SKILL.md.

If 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).

This repo is read at generation time. For a linter that runs over committed prose in CI, see ProseLint; per-rule check-ID mappings are in enforcement/proselint-map.md. Vale users can plug ProseLint via its existing style-pack ecosystem.

The 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.

The 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.

New 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/GOOD 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.

Four 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.

1. 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).
2. Orwell, G. (1946). "Politics and the English Language." Horizon, April 1946. Public domain; freely available online.
3. 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).
4. Gopen, G. D., & Swan, J. A. (1990). "The Science of Scientific Writing." American Scientist, 78(6), pp. 550-558.

5. 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.
6. Bohr, J. (2025). "Show and Tell: Prompt Strategies for Style Control in Multi-Turn LLM Code Generation." arXiv:2511.13972. Motivates the directive + BAD/GOOD example format used throughout RULES.md.

See SOURCES.md for the full bibliography and recommended reading ranges per source.