Index of every page on this site: llms.txt
All skills
cursor avatar

/technical-writing

@0b46ec3
by cursorcursor/plugins18k stars
1,933
Run it yourself

Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages.

Use this Skill: https://skilld.dev/gh/cursor/plugins/technical-writing

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈67 tokens for metadata: the name and description. ≈1k when used: this file.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

This Skill turns off automatic use in Claude Code. Its description stays out of the automatic Skill list by default.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  • Indent code snippets with tabs. Write real paths. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warningtoday3 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    This skill provides stylistic guidelines for technical writing and documentation. It contains no executable code or security risks.

  • Sockettoday

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

Signed by skilld at 0b46ec3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 days ago
disable-model-invocation
true

README badge

README badge for cursor/plugins/technical-writing