| name | write-prose |
| description | Recipe for any English the agent produces in this project, commits, comments, docstrings, ADRs, design docs, skill bodies, changelog, error messages, project guides. Optimizes for terse, humanized prose with no em dashes and no AI tells. Invoke for any prose-writing activity. |
| user-invocable | false |
write-prose
Invoke this skill for any English you produce in this project:
commits, comments, docstrings, ADRs, design docs, skill bodies,
changelog, error messages, project guides. If you are about to write a
sentence of prose, invoke this first.
Read this before writing:
skills/shared/references/style-foundations.md, the canonical craft
reference. It distills Strunk and White's Elements of Style and
Zinsser's On Writing Well into the eight load-bearing rules, and
catalogs the AI tells the project bans.
Also read for project-specific surfaces:
skills/shared/references/prose-style.md, the project's surface
conventions (commit format, ADR format, code-comment idioms, the
no-process-ID rule).
The stance: terse, humanized, no tells
Write like a person who respects the reader's time. Not like a machine
hedging its output. The default failure mode for AI prose is
over-production: too many words, decorative em dashes, sympathetic
throat-clearing, false-affinity adjectives (powerful, robust, seamless).
Reject that default at every sentence.
The four non-negotiables:
- Terse. Omit needless words. The first draft is too long; the
second is shorter. If a sentence can be cut and lose no meaning, cut
it.
- Humanized. Write like a careful person, not a helpful machine. No
apologetic throat-clearing, no false brightness. No filler.
- No em dashes. Never the em dash character. Restructure: a comma, a
colon, a period, or a rewrite. Reaching for the em dash means the
sentence is doing too much.
- No AI tells. No arrow in prose, no hand-written or hand-rolled,
no false-affinity adjectives, no hollow hedging, no rhetorical-question
transitions, no in order to (just to), no utilize or leverage (just
use), no There is openers, no trendy intensifiers (really, very,
super). The full catalog is in
style-foundations.md.
The voice (every surface)
- Plain, direct, technical. No metaphors, no cleverness in names or
headings. A reader six months from now gets the plain meaning on first
read.
- Active voice; present tense for current behavior, past tense for
history.
- State constraints and effects, not narrative.
- No marketing adjectives. If a property matters, state the measurement
or the mechanism.
No internal process identifiers
Code-facing prose describes the code and its behavior, never the process
that produced it. The following must never appear in source comments,
docstrings, test descriptions, or commit messages:
- phase, task, slice, or run identifiers;
- risk-spike or retro labels;
- campaign run artifacts (a plan, checkpoint, or decisions file by
name);
- any other plan, campaign, or orchestration identifier.
A comment that defers to a later point or marks a test as failing on
purpose describes the state, not the process: write a placeholder until
the capability exists, or committed failing until the capability lands,
without the identifier.
Durable project references are allowed and encouraged: ADR references
and design-doc references by path, and named capabilities and modules.
The line: cite durable design artifacts, never ephemeral process IDs.
Why: comments and commit messages are read by future maintainers and
users. Campaign and plan IDs are internal scaffolding, noise outside the
run that produced them, and leaking them makes the code read as
generated.
Per-surface rules
Commit messages
The canonical commit form and category list live in write-commit
(sibling skill). In short: single line, category first, imperative mood,
within 70 characters, effect not diff, no body, no Co-Authored-By or any
other AI or tool attribution trailer, no version numbers, no em dashes.
Invoke write-commit before any commit operation.
Source-code comments
Terse and sparse; clojure.core and the standard library are the
benchmark. The budget is concrete; see prose-style.md for the full
rule. In short: comment only the why (an ownership or lifetime
constraint at a boundary, why a branch is unreachable, a non-obvious
numeric decision), never the what; a comment block is at most three
lines; file density above one line per fifty code lines is a finding;
no banners (a section marker is a single ;;;; label line, label only,
no prose underneath); no commented-out code, no change narration.
Per-language marker idiom:
- C: block comment at the top of the translation unit stating its
single responsibility; inline comments only for constraints the code
cannot say.
- Zig:
//! file-top (one or two lines naming the file's
responsibility), /// doc comments on public declarations whose
contract is not obvious from the signature, // for inline.
- Clojure:
;;;; for section labels, ;;; for namespace-level,
;; for top-level forms, ; for inline.
- Elixir:
@moduledoc and @doc on public modules and functions,
terse inline comments only for the why.
Docstrings
The docstring is the documentation. Every public var and every fn gets
one. One to three lines for most fns: what it returns and the shape of
inputs that require it; never the mechanism. A long docstring (ten or
more lines) is earned by argument surface area (an options map, a spec,
a public primitive), never by a clever implementation. Rationale
belongs in an ADR; cite it by path. Deprecation lives in :deprecated
metadata or a one-line note.
Good: returns the vector of records matching the predicate.
Bad: goes through the index and filters; a ten-line docstring on a
one-line helper.
ADRs
Written when the decision happens (invoke record-decision). Fields:
Title, Date, Context, Decision, Consequences, Alternatives. Title is the
decision itself, readable in the index without opening the file. Context
is neutral. Decision is one paragraph, present tense. Consequences
include the costs. Alternatives get their real strengths before the
rejection. About one screenful (40 to 60 lines).
Design docs
The existing design docs are the exemplar. Match their terse, plain
voice. Each section has a single topic; cross-reference by path rather
than restating. A design doc is the spec; a substantive edit is usually
an ADR in disguise (use record-decision, then update the doc to cite
it).
Skill bodies (skills/*/SKILL.md and references)
The skill body is the procedure an agent follows. Imperative voice (run
X, dispatch Y, do not Z). Numbered steps for sequential procedure,
bullets for non-ordered rules. Front-load the contract and the return;
defer the rationale. Skill prose is itself reviewed by check-style
against prose-style.md.
Changelog entries
User-facing voice, written from the user's perspective. Category prefix
so the section groups. Lead with the effect, not the cause. One to five
lines once wrapped. Never reference internal cycle names, round numbers,
finding ids, or run paths. See write-changelog for the full recipe.
User-facing error messages
An error message names the failing operation, never a bare error; leads
with what the user was doing; states the constraint that was violated;
suggests the next step if there is one.
Good: the file header claims a terabyte of data but the file is 12 KB.
The file is corrupt; the load was refused.
Bad: load failed.
Bad: error: invalid input.
Project guides (CLAUDE.md, README.md)
Plain, direct, scannable. Headings every few paragraphs. Bullet lists
for enumerations. Code blocks for commands and paths. Update the guide
when a new skill or agent lands; update the README when the project
shape changes.
Pre-flight before submitting any prose
Run the prose through this check (from style-foundations.md):
- Read it aloud once. The ear catches clutter the eye misses.
- Cut. If you cannot find words to cut, read again.
- Search for the em dash character. If any appears, restructure.
- Search for adverbs ending in ly. Most can go.
- Search for that. Half of them are filler.
- Search for the AI tells in
style-foundations.md. Find one, fix one.
- Search for internal process IDs (phase, task, slice, run, plan,
retro labels). Rephrase to describe the code.
- End each sentence on its point, not its preamble.
- Check parallelism in lists and headings.
Boundaries
Owns: the prose craft for every human-readable surface in the project.
Cites: skills/shared/references/style-foundations.md (the craft
canon) and skills/shared/references/prose-style.md (the project
surfaces). Siblings: write-commit owns the commit-specific form;
write-changelog owns the changelog recipe; record-decision owns the ADR
shape; check-style owns the prose-review dimension that enforces this
standard. Does not decide content (that is the owning skill's job); it
decides how the content reads.
When in doubt
Read style-foundations.md again. If a prose choice is not covered
there, capture the question via capture-guidance for the next
incorporate-feedback pass; do not guess.
