writing
These are the guidelines for writing and revising text.
- The way human readers read and think follows humanity-and-humanness
- Japanese phrasing follows in philtzjp/skills
- The guidelines in this skill build on top of those
Why this skill is needed and the state we want to reach
The reason this skill is needed is that AI reflexively assembles sentences from learned patterns of expository writing rather than starting from what it wants the reader to judge. As a result, reasons are missing, and information that can be derived from the code—and will become stale—increases. Reflexive interpretive cues create unnatural beats. The entire text becomes flat in a single cognitive mode. AI also treats the reader as a version of itself that can read exactly what is written. Human readers fill in gaps through inference; they cannot keep track of items, follow the flow, or retain what they have read. This habit tires the reader and buries the criteria that matter most.
With this skill, the desired state is a text that lets readers receive the writer's judgment and its rationale in a single reading and continue to the end.
Fundamental principles
Guidelines should not be applied mechanically as sentence patterns or prohibitions. The first question is not “How should this be revised?” but “What does this revision preserve in the text?” Judge by the function the text serves, not by its form.
Structure aligned with how readers read
Humans read in sequence and build understanding in the order they read. They scan the whole to get an overview before moving into details. The structure should match this behavior.
- Include only one kind of document in a document
- Before listing rules, explain what would happen without those rules
- Make the title and opening sufficient to show what kind of document it is and what it preserves
- Describe what kind of document it is in a short prose paragraph, then list what it preserves as bullet points
- Turn parallel items into a list; do not fold them into prose
- Give a one-line summary to indexes that point to another file or section
- Keep only one independent judgment in a sentence
- Make headings at the same level answer the same question
- Give headings the main point, not merely the topic. Use verb phrases for procedural headings and noun phrases for conceptual headings
Documents come in four types: procedures for doing work, references containing facts for doing work, explanations for understanding, and procedures for learning. Readers change how they read according to the type, so placing background material in a procedure or persuasive content in a reference prevents them from switching reading modes. If the content becomes mixed, split it into separate documents and link them.
When headings at the same level do not share a consistent perspective, readers cannot grasp the axis along which the material is divided, even after scanning the list. Do not place sections on rules, procedures, and subject matter at the same level.
Listing rules first and adding reasons afterward prevents questions from arising, so no flow develops. The progression from the necessary reason, through the desired state and fundamental principles, to the rules creates this flow throughout the document.
If a sentence contains multiple judgments, humans skim it and fill in the gaps. AI tries to execute all of them. This creates a mismatch between how each recognizes the text.
Designing rhythm
Dense prose becomes boring not because it contains a lot of information, but because the entire text is written in the same cognitive mode. Switch the reader's cognitive mode among observing, hesitating, becoming convinced, and double-checking, always leaving a reason to continue reading.
- Design rhythm as a shift in cognitive mode, not as an increase or decrease in information density
- Always keep one thread of unresolved tension open
- Write in the voice of a participant thinking through the issue, not in the voice of someone explaining an already settled conclusion
- Draw the material for beats, tension, and release only from the situation
- Realize the device through the content; do not announce it
- Do not cut sentences merely to create a beat
When all tension closes at once, the reader may stop reading. Unresolved tension can be an unanswered question, an unverified confidence, or an answer promised for later.
A situation consists of events in the subject world, data, statements, and the narrator's state of judgment. In expository writing with no scene, the subject's own properties and the reader's inferences or counterquestions serve as the situation. Where the situation provides no material, add nothing and leave the passage flat. Making the prose itself the subject of a sentence in order to create rhythm violates this rule.
A sentence such as “First, give half of the answer,” which describes an operation to be performed next, is itself bad writing. If the device works, the reader should not notice its presence.
Cutting sentences that provide context needed for introducing scope, perspective, comparison axes, or unresolved matters is not rhythm; it is omission. Edit for greater density only on the basis of previously shared context.
Guidelines
When writing expository text, read all of the following as well.
- . Write the purpose and reason
no-perishable-information
- . Place punctuation at role boundaries and where meaning becomes certain
- . Put the purpose before the means
- . Use noun phrases in headings and bullet points
Use cases
contains procedures for writing specific kinds of text.
- . Write documents read by AI, such as SKILL.md, AGENTS.md, and CLAUDE.md
- . Write a README.md that helps people decide whether it is for them and get started
- . Write novels