メニュー
Writing standards for code comments, documentation, specs, PRDs, and team communication. Applies RFC 2119 requirement language and token-efficient writing.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/simpleapps-com/augur-skills --skill writing-styleコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
| name | writing-style |
| description | Writing standards for code comments, documentation, specs, PRDs, and team communication. Applies RFC 2119 requirement language and token-efficient writing. |
Apply these standards to all written output: code comments, docs, specs, PRDs, wiki pages, commit messages, and team communication.
Spec: https://www.rfc-editor.org/rfc/rfc2119
Every directive MUST use an RFC 2119 keyword in ALL CAPS. This applies to wikis, skills, rules, specs, PRDs, issue acceptance criteria, and any content that tells a reader or agent what to do. Agents weight capitalized keywords more reliably than prose; soft language is silently downgraded or ignored.
Decision framework: Does the system break without it? → MUST. Degrades? → SHOULD. No impact? → MAY.
| Soft phrase | Rewrite as |
|---|---|
| always / never | MUST / MUST NOT |
| be sure to / make sure | MUST |
| don't / do not | MUST NOT |
| don't forget to | MUST |
| needs to / has to | MUST |
| try to / aim to | SHOULD |
| should probably / ideally | SHOULD |
| can / feel free to | MAY |
| avoid | SHOULD NOT |
| remember to | MUST |
Before saving any directive sentence, confirm it contains one of: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY. If it doesn't, rewrite it or demote it to descriptive prose (no directive verb).
Use lowercase "should/must/may" only for descriptive prose, not directives: "the build should finish in under a minute" (observation) vs "the build SHOULD finish in under a minute" (requirement). If the sentence tells someone what to do, it's a directive. Capitalize.
In CLAUDE.md and skill instructions, use "YOU MUST" or "IMPORTANT" as emphasis markers to improve adherence to critical rules.
Keywords are binding on the reader, not suggestions to weigh against convenience. When you encounter a keyword while executing work:
The failure mode this prevents: an agent reads "tests MUST cover the edge case", finds writing the test tedious, and silently demotes it to "tests should cover the edge case where practical". That is the agent overriding the writer. MUST means MUST. If you can't comply, stop and report. Do not proceed with a weakened version.
Prior examples in the current session do NOT override a MUST. If session context shows code that violates a MUST from the wiki/skill/spec, the session code is wrong. Flag it, do not use it as permission to violate the MUST.
A MUST NOT placed after the steps it governs is read too late to prevent anything. Aerospace documentation standards put warnings and cautions before the step for exactly this reason.
versioning rule is the model: "MUST NOT deploy without explicit user approval" precedes the deploy steps.RFC 2119 is controlled language applied to one word class. It fixes the sense of modal verbs so they cannot be read two ways. ASD-STE100 (Simplified Technical English, the aerospace maintenance standard from ASD's STE Maintenance Group) applies the same move to the whole document under one constraint: one word, one meaning, one part of speech. Its approved dictionary is aerospace vocabulary and MUST NOT be adopted here. Two of its rules earn their keep in agent-facing writing.
Pick one word per concept and use only that word. A synonym reads as a new concept to an agent, which then hunts for a distinction that does not exist.
rules/, a skill is on-demand markdown in skills/, and a command is a skill invoked by slash. MUST NOT substitute "guardrail", "convention", or "standard" for any of them."This", "it", and "that" pointing back at a whole clause is the most common ambiguity in technical prose, and the one agents most often resolve wrongly.
Repeating a noun costs a few tokens. Resolving the wrong referent costs a wrong edit.
Every token costs time, money, and cognitive load. Be concise without losing clarity.
Why this matters: brevity is front-loaded effort. A short text costs the author more and every reader less. The work doesn't vanish, it moves from the author once to every reader never (the same ledger as "code is a liability": ongoing cost, one-time value). As Pascal wrote in 1657, "I have made this longer than usual because I have not had time to make it shorter." The line is commonly misattributed to Mark Twain.
Rules:
auth.ts:45 not "authentication file line 45"By audience:
By format:
When to expand:
When to cut:
Default to brief. Expand only when the reader cannot infer meaning from context. Two sentences that answer the question beat two pages that fill the context window.
A canonical phrase paired with the author and work names a whole discipline's concept cluster in a handful of tokens. For an agent, this shifts the reasoning pool: "improving daily work" alone pulls from a generic improvement cluster; "Gene Kim's The Phoenix Project, the DevOps Second Way" activates feedback loops, toil reduction, blameless post-mortems, value streams, and the rest of the adjacent vocabulary. Cheap tokens, richer reasoning.
When it fits:
work-habits. Goldratt's commission/omission errors in /sanity-check. RFC 2119 in writing-style. Each one names a body of thought the agent is expected to apply.Anti-patterns:
This is a technique, not a rule. Most skills should not invoke an external discipline at all. Use it when a skill's guidance genuinely derives from a named body of thought, and the agent will reason better for being told which one.
The em-dash (—) is one of the strongest tells of AI-generated text. LLMs over-produce it dramatically, far beyond how humans punctuate. Readers (especially developers and clients reading client-facing posts) increasingly read em-dashes as "this was written by AI."
SHOULD NOT use em-dashes. Almost every em-dash can be replaced with simpler, more natural punctuation:
| Em-dash usage | Replace with |
|---|---|
| Parenthetical aside | Comma, or parentheses if truly aside |
| Sentence break for emphasis | Period (start a new sentence) |
| Introducing a list or example | Colon |
| Connecting two related clauses | Period or semicolon |
| Range (5—10) | En-dash (–) or "to" |
Examples:
❌ The wiki is the spec — the repo is the implementation.
✅ The wiki is the spec. The repo is the implementation.
❌ Cross-linking turns files into a knowledge graph — each link is an attention signal.
✅ Cross-linking turns files into a knowledge graph. Each link is an attention signal.
❌ Three audiences read the wiki — junior devs, senior devs, and AI agents.
✅ Three audiences read the wiki: junior devs, senior devs, and AI agents.
❌ Memory is unauditable — the user cannot easily review what's saved.
✅ Memory is unauditable. The user cannot easily review what's saved.
MAY use em-dashes only when:
When editing existing content, replace em-dashes opportunistically. When writing new content, default to periods, commas, and colons. If you find yourself reaching for —, that is a signal to break the sentence into two.
Lists with no inherent order (deny rules, config arrays, feature lists, bullet-point explanations) MUST be sorted alphabetically. Alphabetical order makes items easier to find and minimizes git diffs. New entries slot into a predictable position instead of appending at the end.
Applies to JSON arrays, markdown bullet lists, table rows, and any unordered collection.
Use descriptive variable and function names. Abbreviations save keystrokes but cost readability. The human reviewing your output MUST be able to understand the code without deciphering names. Short names also collide with terminology in the surrounding conversation and confuse the reader (e.g. using p as a path variable while the discussion is about a payment path; the reader will read p as "payment", not "path").
$groupQuantity not $gq, cartItem not ci, filePath not p, response not ri, j, k)id, url, db) are finecalculateShippingCost not calcShipReasoning depth is set by effort level, not by prose. /effort accepts low, medium, high, xhigh, and max (available levels depend on the model), plus ultracode, which is a Claude Code setting rather than a model level. A skill MAY pin its own level with the effort frontmatter field.
ultrathink is the one recognised keyword: include it anywhere in a prompt or in skill content to request deeper reasoning for that turn without changing the session effort. think, think hard, and think more are NOT keywords. They are passed through as ordinary prompt text, so MUST NOT be written as if they control anything.
Basecamp 2 integration via MCP. Covers MCP tool reference, URL parsing, authentication, Chrome fallback, attachments, and site-info documents. Use when reading or writing Basecamp data.
Bash command conventions. One command per call, use dedicated tools over shell equivalents, check wiki for approved commands. Load this skill before running Bash commands.
When working in load-bearing code (the 5-10% where correctness matters most: money math, auth, concurrency, state machines, security boundaries), tighten the type system first, then add formal contracts (@requires/@ensures/@invariant/@trusted) in the host language's native comment syntax. Use Unicode glyphs (∀, ∈, ≥, ℕ) for AI priming, paired with ASCII gloss for human readers. The contracts pay off through three independent mechanisms: priming agent reasoning, surfacing tests, and adding context-window value that agents themselves report. Drift between contract and code is a defect.
