technical-writing
Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or, in a Pstack task, when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.
How do I install this agent skill?
npx skills add https://github.com/christofferbergj/agent-skills --skill technical-writingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The technical-writing skill provides stylistic guidelines for documentation without any associated security risks. It follows industry standards like Diátaxis and Google developer style.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Technical writing
Write so a tired engineer understands on the first read.
- Cut every word that does no work.
- Use the short, everyday word: "use", not "utilize".
- When a rule makes a sentence worse, fix the sentence another way or leave it alone.
- Write the real symbol, file, flag, or command name, not a synonym or a description of it.
- Don't invent jargon. Use the words a developer would say out loud. Say what a named pattern means the first time.
Vary the rhythm
- Mix sentence lengths. Split the sentence that carries two thoughts. Keep the long sentence that carries one.
- Have a view in explanation. Keep reference dry.
- Be specific. Not "schema changes can cause issues" but "a column rename fails the build".
Pick the mode first (Diátaxis)
One document, one mode. Don't mix modes. Split and link instead.
- Tutorial: learning by doing. Say what the learner will build. Every step produces a visible result, and you say what they should see. Explanation gets one clause and a link.
- How-to: steps to a goal. Solve the reader's problem. Assume competence. Action only. Allow forks. Name the guide by the task.
- Reference: facts for lookup. Only describe. Be dry, complete, and sure. Mirror the structure of the thing described.
- Explanation: understanding and why. One bounded topic. Give context: design decisions, history, constraints, alternatives. Opinion is allowed here and nowhere else.
Write sentences to the reader (Google developer style)
- Talk to the reader as "you", in the present tense.
- Say who does what. Passive is fine only when the actor is unknown or beside the point.
- Write instructions as commands. Put the condition before the instruction and the common case first.
- No buzzwords, no figurative language, no "please", and never "simply", "easy", or "quickly" in a procedure.
- Don't pre-announce, and don't start consecutive sentences with the same phrase.
- Link with words that say where the link goes.
- Headings carry the point, in sentence case. One h1 per page, no skipped levels.
- Numbered lists for sequences, bullets for everything else. Introduce a list with a complete sentence. Keep items parallel.
- Code goes in code font. UI elements go in bold. Use serial commas. Drop "etc.".
Make statements load one at a time (STE rules)
- One instruction per sentence. One thought per sentence everywhere else.
- Split instructions longer than about 20 words and other sentences longer than about 25.
- Put the warning or condition before the step it guards.
- Keep "the" and "a".
- Give each word one meaning, and pick one word per action.
- Write procedures as direct commands, never as narration and never in the passive.
- Avoid "-ing" words where you can.
Leave no sentence open to two readings (Global English)
- Keep words like "only" and "not" next to the word they change.
- Break up long noun strings.
- Make every "it", "they", and "this" point at one obvious thing. Never use "this" or "which" to point at a whole clause.
- Don't drop verbs, or the small words that show structure, such as "that".
- Repeat the article in a series when it prevents a misread. Say which parts "and" or "or" joins.
- Use periods, not semicolons or em dashes. No slashes, and no "(s)". Make text in parentheses a full grammatical unit.
- Call each thing by one name, everywhere.
- Skip idioms, colloquialisms, Latin abbreviations, and metaphors.
Voice and repo specifics
- Apply the /unslop skill to every doc this skill touches. That skill owns the slop-pattern catalog: AI vocabulary, filler, hedging, formatting tells.
- PR descriptions and commit messages are writing too. Every layer except Diátaxis applies to them. A PR body is a briefing that a reviewer can read in under a minute. Do not paste swarm logs, SHA lists, or metric tables. Link them.
- Product UI strings are not documentation. Use your product's copy guidelines for those.
- Match the repository's code formatting in snippets. Write real paths. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/christofferbergj/agent-skills/technical-writing">View technical-writing on skillZs</a>