doc-style-write

Applies wording conventions when writing rules, specs, READMEs, and code comments.

1|Updated Jan 14, 2024
One-click install
npx skills add https://github.com/Eyhenij/rt-tools --skill doc-style-write-eyhenij
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: doc-style-write
Source: https://github.com/Eyhenij/rt-tools/tree/main/.claude/skills/doc-style-write
Command: npx skills add https://github.com/Eyhenij/rt-tools --skill doc-style-write-eyhenij

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Project prose drifts into vague, unverifiable, or overly ornate wording: rules padded with justification, claims about the future, facts recalled from memory instead of checked, and metaphors that read poorly. This Skill enforces a consistent documentation style so every rule, spec item, README section, and code comment states what is true in plain, checkable language. ## Core Features & Use Cases - One-sentence rules: Keeps each rule to a single verifiable sentence, moving justification and alternatives into a separate pitfalls section. - Fact verification discipline: Requires checking code, branches, and command output directly rather than writing numbers or behavior from memory. - Glossary workflow: Defines a four-step process for introducing new terms, including searching rejected words before adding new ones. - Use Case: When drafting a spec item like "a booking has at least one adult," the Skill guides you to drop implementation details (database constraints, write paths), avoid future claims, and phrase it as a single testable statement. ## Quick Start Ask the assistant to review or rewrite a rule, spec item, README paragraph, or code comment using the doc-style wording conventions.

Frequently Asked Questions about doc-style-write

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good project rule or spec item?

Write the rule as one sentence stating what is true, with at most two sentences about what breaks otherwise. Move justification and alternatives into a pitfalls section, and avoid naming where the rule is enforced in code.

How should code comments be written in this style?

A comment answers why the code is so and not otherwise, only when that is not obvious. What a line does is visible from the line itself, so rename unclear code first before adding explanatory comments.

Can documentation mention features that are not planned?

No. Claims about the future like "not planned" or "will not be" cannot be checked and silently go stale. State what is not done and why, and record open decisions as numbered open questions instead.

Why should numbers in documents be recomputed instead of recalled?

A number from memory is indistinguishable from a measured one and may be wrong. The Skill requires recomputing any number with a command in the same turn the text is written, and verifying the command actually measures what was asked.

When should a new word be added to the project glossary?

Add a word when it has a specific meaning in the project, but first search the full glossary including rejected words. Each entry pairs the word with its definition and must be laid out in the same change with checks passing.