About

Imported from shipshitdev/skills (skills/technical-writing/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill technical-writing. Copyright stays with the author (MIT).

Technical writing

Name: technical-writing
Author: shipshitdev

The goal is writing a tired engineer understands on the first read. Four layers: what kind of document this is, how sentences address the reader, how much each sentence carries, and whether any sentence reads two ways.

Companion to docs (repo-convention docs writer) and deslop (prose-tell catalog). Apply references/prose-slop.md from the selected deslop skill directory to every doc this skill touches.

Authorized Scope

Apply this engine only within the user's requested task and existing explicit authorization. Loading or delegating to it grants no additional authority. Preserve report-only restrictions and the caller's target, host, provider, and cost limits. Existing approval satisfies a gate only for the same actions and scope; obtain approval before expanding them. Forward these limits to delegates.

Contract

Inputs:

A doc, RFC, README, PR description, or commit message to write or review

Outputs:

The rewritten surface, in one Diátaxis mode when the artifact is a document

Creates/Modifies:

The named prose files or git metadata the caller asked for

External Side Effects:

None beyond those writes

Confirmation Required:

None for drafting. Confirm before committing.

Delegates To:

File pointer: references/prose-slop.md from the selected deslop skill directory

Rules above the layers

Cut every word that does no work.
Use the short, everyday word.
When a rule makes a sentence worse, fix the sentence another way.
The codebase is the word list. Write the real symbol, file, flag, or command name.

Pick the mode first (Diátaxis)

Action + learning: tutorial.
Action + work: how-to.
Understanding + work: reference.
Understanding + learning: explanation.

Do not mix modes. Split and link instead. Source: diataxis.fr.

Tutorial. Open by saying what the learner will build. Every step produces a visible result. Write as "we", in commands.

How-to. Solve a problem a person has. Assume competence. Action only. Name the guide by the task.

Reference. Describe. Only describe. Mirror the structure of the thing described.

Explanation. One bounded topic. Anchor on a real why. Opinion is allowed here and nowhere else.

Sentences (Google developer style)

Talk to the reader as "you", present tense. Say who does what. Instructions as commands. Condition before the instruction. Common case first. Sentence-case headings. Numbered lists for sequences. Source: developers.google.com/style.

Load one thought at a time (STE)

One instruction per sentence. Split instructions longer than about 20 words. Keep "the" and "a". One word per action, then keep it. Source: asd-ste100.org (Issue 9, 2025).

Leave no sentence open to two readings (Global English)

Keep "only" and "not" next to the word they change. Break up long noun strings. Make every "it", "they", and "this" point at one thing. No slashes. Call each thing by one name. Source: Kohl, The Global English Style Guide.

Voice

PR descriptions and commit messages are writing too. Every layer except Diátaxis applies to them.
Product UI strings are not documentation.
Write real paths and real symbols. Make every count true at the commit that lands it.

Review checklist

Is each file one Diátaxis mode?
Is every instruction a command, with its condition in front?
Does any sentence carry two thoughts? Split it.
Can any word be cut? Cut it.
Is "only" next to the word it changes?
Does each thing have exactly one name?
Would a developer say these words out loud?
Are symbols, paths, and counts real at this commit?

Technical Writing procedure

Read technical-writing procedure when running this workflow. Apply the authorized scope and mode of this entry point to every step. Resolve other skills through this distribution’s active catalog; resolve resources relative to the installed skill directory.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-technical-writing/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-technical-writing.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-technical-writing",
  "kind": "skill",
  "name": "technical-writing",
  "description": "Layered technical-writing standard for docs, RFCs, READMEs, PR descriptions, and commit messages. Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for technical-writing or when writing or reviewing those surfaces.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "docs",
      "writing",
      "diataxis",
      "style",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Layered technical-writing standard for docs, RFCs, READMEs, PR descriptions, and commit messages. Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for technical-writing or when writing or reviewing those surfaces."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/technical-writing/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/technical-writing/SKILL.md",
      "key": "shipshitdev/skills/skills/technical-writing/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Technical writing\n\nThe goal is writing a tired engineer understands on the first read.\nFour layers: what kind of document this is, how sentences address the\nreader, how much each sentence carries, and whether any sentence\nreads two ways.\n\nCompanion to `docs` (repo-convention docs writer) and `deslop`\n(prose-tell catalog). Apply\n`references/prose-slop.md` from the selected `deslop` skill directory to every doc this skill\ntouches.\n\n## Authorized Scope\n\nApply this engine only within the user's requested task and existing explicit\nauthorization. Loading or delegating to it grants no additional a",
  "cost": {
    "context_tokens": 1000
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-technical-writing/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.