# Technical Writing > > - **Type:** Skill - **Install:** `agentstack add skill-officialunofficial-skills-technical-writing` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [officialunofficial](https://agentstack.voostack.com/s/officialunofficial) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [officialunofficial](https://github.com/officialunofficial) - **Source:** https://github.com/officialunofficial/skills/tree/main/skills/productivity/technical-writing ## Install ```sh agentstack add skill-officialunofficial-skills-technical-writing ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Technical writing Documentation is the single source of truth for how a system behaves, and every string a person reads shapes their trust in it. Write for clarity, accuracy, and completeness. When you can show instead of tell, show: an example lands faster than an explanation. This skill is the durable, behavior-changing core. The exhaustive mechanics (units, possessives, abbreviations, keyboard shortcuts, code-doc conventions) live in [REFERENCE.md](REFERENCE.md) — consult it when a specific question comes up. Project-specific vocabulary (a glossary, wire-format terms, product names) belongs in that project's own style guide; link the canonical definition on first use. ## Voice and tone Three words are the touchstone: **clear, direct, specific.** Every rule below serves one of them. - **Second person.** Write "you", not "we". Reserve "we" for the rare moment the maintainers address the reader directly (a security advisory, a deprecation). - **Present tense.** Say what the system does now, not what it "will" do. - **Active voice.** Name the actor. "The command writes a lockfile", not "a lockfile is written". Passive constructions lean on "was" and "by" — hunt them. - **Plain American English**, readable by every English speaker, not only native ones. Prefer the shorter forms ("behavior", "canceled"). - **Gender-neutral.** Singular "they"; address groups as developers, operators, maintainers, or callers. ## Sentence craft Write short sentences. One thought each is punchier than three crammed together. - Use action verbs and subject-verb-object order. Cut clunky phrases. Drop any adjective or adverb that doesn't change the meaning. - After a long sentence, write a short one. The contrast snaps attention back. - Don't repeat a word inside one sentence, and don't open or close a sentence with the word that opened or closed the one before it. - Prefer splitting a phrase into two sentences over gluing clauses with a comma. When you must join them, use an em dash or a connecting word ("then", "however", "so"), never a bare comma between two independent clauses. ## Formatting - **Headings in sentence case.** Capitalize only the first word and real proper nouns, kept at their canonical casing (GitHub, BLAKE3, in-toto). Never Title Case a heading for emphasis. The page title is the H1; top-level sections are H2; don't skip levels. - **Link the noun phrase, never "here".** The link text names its destination and reads as the call to action: "see the [packfile specification](#)", not "the spec is available [here](#)". Use relative links between files in the same repo. - **Inline code is for code.** Back-tick identifiers, paths, commands, and literal output only. Do not use inline code, bold, or caps as a substitute for emphasis. - **Bold file and directory names** (**.mkit/**, **src/**, **.cbor**) rather than back-ticking them. - **No emojis** — not in prose, headings, callouts, or changelog entries. - **Spell out symbols in prose**: "and" not "&", "plus" not "+" (except in keyboard shortcuts). - **Em dashes**: write `—` rather than a hyphen or the literal `—`. Markdown renders the entity reliably, and the literal `—` is the most common tell of AI-assisted writing — flag it in review. - Numbered lists start at 1. Use Oxford commas in prose; if a sentence sags under its commas, split it rather than dropping the Oxford comma. ## User-facing copy Any string a person reads is user-facing copy: stdout and stderr, error and progress messages, `--help` text, prompts, buttons, the web UI, the docs site. A dynamic `format!`/template string counts. Every string earns its place by doing at least one of three things: say what happened, say what happens next, or say what to do. Get to the point. - **State facts, not feelings.** No "please", "sorry", "unfortunately". Write `non-fast-forward push rejected: fetch and retry`, not `Sorry, we couldn't push your changes. Please try again.` - **Every error carries the next action.** The exit code carries the class; the message carries the specifics and, when one exists, the recovery step. - **Plain terms first.** Keep spec jargon in the specs. In help text, errors, and UI, prefer the plain term ("attestation envelope"); expand or link a precise term on first use. - **Exact verbs on prompts and buttons.** A confirmation names its action — "Delete branch", "Overwrite key" — never "Yes" or "OK". Prompt copy is a full sentence saying what happens and why. - **Same state, same words.** Never word one state two ways across surfaces (CLI vs UI vs a JSON `message`). Route a repeated string through one helper. - **Sentence case everywhere** — headings, labels, buttons, table headers. Title case only for real proper nouns. - **Fidelity wins over style.** Where output is pinned byte-for-byte to another tool's (a compatibility format), match that tool's wording even when it breaks these rules. Note why. ## Before you ship Run this pass on any diff that touches prose or copy: 1. **Grep the diff** for `please`, `sorry`, `unfortunately`, `simply`, and `easy`. Each is almost always cuttable. ("Simply" and "easy" tell the reader their trouble is their own fault.) 2. **Search for the literal `—`** you didn't type as `—` — it's the AI-writing giveaway. 3. **Check for a duplicated string** already worded by a helper; reuse it instead of hand-writing the state again. 4. **Read it once for passive voice and long sentences.** Split the longest sentence on the page. Turn one "was …" into an active clause. 5. **Confirm headings are sentence case** and links name their destination. For anything this skill doesn't cover, fall back to the [Google developer documentation style guide](https://developers.google.com/style) and, for the words to strike, [Words to avoid in educational writing](https://css-tricks.com/words-avoid-educational-writing/). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [officialunofficial](https://github.com/officialunofficial) - **Source:** [officialunofficial/skills](https://github.com/officialunofficial/skills) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-officialunofficial-skills-technical-writing - Seller: https://agentstack.voostack.com/s/officialunofficial - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.