technical-writing

Applies Diátaxis, Google style, STE, and Global English rules to technical documentation.

Updated Aug 22, 2026
One-click install
npx skills add https://github.com/squidllee/skills --skill technical-writing-squidllee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: technical-writing
Source: https://github.com/squidllee/skills/tree/main/technical-writing
Command: npx skills add https://github.com/squidllee/skills --skill technical-writing-squidllee

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Technical docs often confuse readers with mixed document types, passive voice, ambiguous sentences, and jargon. This Skill gives you a four-layer standard for writing and reviewing docs, RFCs, READMEs, PR descriptions, and commit messages so a tired engineer understands them on the first read. ## Core Features & Use Cases - Diátaxis mode selection: Classify each document as tutorial, how-to, reference, or explanation, and keep modes from mixing. - Sentence-level rules: Apply Google developer style (active voice, commands, condition-first), STE limits (one instruction per sentence), and Global English disambiguation (pronoun clarity, no noun strings). - Review checklist: Run an 8-point checklist covering mode purity, command phrasing, word economy, naming consistency, and factual accuracy of symbols and counts. - Use Case: Paste a draft README section and ask for a review; the Skill rewrites passive constructions, breaks up ambiguous sentences, replaces jargon with real symbol names, and flags mixed Diátaxis modes. ## Quick Start Review this README draft using the technical-writing standard and rewrite any sentences that violate the four layers.

Frequently Asked Questions about technical-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I choose between a tutorial, how-to, reference, and explanation?▼

Use the Diátaxis compass with two questions: does the content inform action or understanding, and does it serve learning or work. Action plus learning is a tutorial, action plus work is a how-to, understanding plus work is reference, and understanding plus learning is explanation.

How do I write clearer technical documentation for developers?▼

Address the reader as "you" in present tense, write instructions as commands with conditions first, keep one thought per sentence, and use real symbol and file names instead of descriptions. Cut every word that does no work.

What is the difference between Google developer style and STE rules?▼

Google developer style governs how sentences address the reader: active voice, commands, condition-before-instruction. STE rules govern sentence load: one instruction per sentence, roughly 20-word limits for procedures, and warnings placed before the steps they guard.

Does this writing standard apply to PR descriptions and commit messages?▼

Yes. Every layer except Diátaxis applies to PR descriptions and commit messages, since they are writing too. Product UI strings are excluded; those follow your product's copy guidelines instead.

When should I not follow a writing rule?▼

When a rule makes a sentence worse, fix the sentence another way or leave it alone. The rules serve the reader, and a sentence that follows every rule but reads like machine output has failed its purpose.