writing-simple-and-direct
Skill0 starsChanged 25 days agoApache-2.0View on GitHub
House prose style distilled from Barzun's Simple and Direct. Eight kernel rules with expansions, before/after patterns, and a review protocol for every prose artifact (SITREPs, reviews, proposals, ADRs, session docs, backbriefs, commit messages). Use when writing or reviewing any prose artifact.
In this repository13 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- configuration-managementSkill
- designing-clear-data-displaysSkill
- lake-conventionsSkill
- maintaining-project-contextSkill
- maintaining-the-common-operating-pictureSkill
- maintaining-ubiquitous-languageSkill
- python-venv-managementSkill
- recording-architecture-decisionsSkill
- shift-left-testingSkill
- traversing-the-knowledge-baseSkill
- using-topic-branchesSkill
- verifying-claimsSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Prefer the concrete word: name the file, the number, the failure.
- Distinctive: line 32
Read it back; if you would not say it, do not write it.
- Distinctive: line 33
No em dashes in running prose.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Simple and Direct
House style for prose. Three goals: clearer communication for humans, fewer tokens per artifact, and removal of machine-prose defaults from our output. This SKILL.md is the entry point; expansions, examples, and the review protocol live in sidecar files loaded on demand.
Scope, stated once: document schemas (TCS, CONOP-FORMAT, OPORD-FORMAT) define what a document contains. This skill defines how the words go. Never cut a required section to save tokens. A chart that could be a table or a sentence is not this skill's tokens to cut; that finding is the figure skill's pre-question (designing-clear-data-displays).
Philosophy: Have a point. Make it in the fewest words that keep it true.
When to Use
- Writing any prose artifact: SITREP, review, proposal, ADR, session doc, backbrief, commit message, PR text
- Reviewing prose artifacts (code-reviewer loads
REVIEWING.mdfor document reviews) - Writing docstrings and comments (apply the rules; enforcement stays on artifacts)
- Adopting this skill in a downstream repo (
ADOPTION.md, once)
The Kernel
Eight rules. The ambient copy lives in CLAUDE.md (see ADOPTION.md); RULES.md expands each one with its test.
- Have a point; state it in the first sentence. No throat-clearing.
- Prefer the concrete word: name the file, the number, the failure.
- One idea per sentence. Link sentences; do not pack them.
- Active voice unless the actor is unknown or irrelevant.
- Cut cruft words. The banned list lives in LANGUAGE.md.
- Hedge with numbers or not at all.
- Read it back; if you would not say it, do not write it.
- No em dashes in running prose. Choose the mark that states the relationship.
Quick Reference
The Punctuation Table (rule 8)
| Relationship | Mark |
| Announces or expands | Colon |
| Balances two complete thoughts | Semicolon |
| Separate ideas | Period |
| Stated logic (and, but, because, so) | Conjunction |
| True aside | Parentheses |
Cruft Starter List (rule 5)
leverage, utilize, robust, seamless, comprehensive, facilitate, streamline, delve, crucial, holistic; "it should be noted that"; "in order to" outside mission statements. Authoritative list: LANGUAGE.md.
Token Economy
Simple and direct is usually cheap, and the exception is instructive. In EXAMPLES.md, cruft-heavy prose shrinks by half or more after revision. Under-specified prose grows, because facts cost more words than fog. Both are correct outcomes. Model output skews toward cruft, so net savings are real; but a document that got longer and truer also followed this skill. Expect the largest savings in written artifacts. Effects on reasoning traces are second-order; do not count on them.
What This Skill Is Not
- Not a persona. "Write like Barzun" is the roleplay that design principle 5 forbids. These are named rules with tests, applied like any other schema.
- Not a length cap. Completeness comes from the document schemas. Cut words, never required fields. A short OPORD missing its exit criteria is not simple; it is malformed.
- Not retroactive. Existing docs are grandfathered, and session docs and reviews are records; leave them. The rules apply to new and revised prose.
Sidecar Files
Loaded on demand when this SKILL.md cites them. Read only the ones relevant to the task at hand.
- RULES.md: each kernel rule expanded with the failure it counters and the test that catches it. Read when writing any artifact longer than a commit message.
- EXAMPLES.md: six domain-native before/after pairs with word counts, including the pair that grows. Read when a rule feels abstract.
- REVIEWING.md: the review protocol for prose: pass order, finding format, severity mapping, what not to flag. Read by code-reviewer before reviewing any prose artifact.
- ADOPTION.md: the CLAUDE.md kernel block, LANGUAGE.md additions, reviewer checklist line, the optional Vale seam, and propagation notes. Read once per repo.
References
- Jacques Barzun, Simple and Direct: A Rhetoric for Writers (1975; 4th ed. 2001). Six parts (diction, linking, tone, meaning, composition, revision) and twenty numbered principles. Distilled here, not transcribed.
- LANGUAGE.md: the banned-word mechanism this skill extends.
- CLAUDE.md "Simplicity First": the code-side twin of this skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

