SkillAgentSearch skills...

technical-documentation

Audit, write, and improve developer documentation using Google''s Developer Documentation Style Guide and Technical Writing courses.

Install / Use

npx skills add wondelai/skills --skill technical-documentation

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

91/100

Supported Platforms

Universal

Our assessment of technical-documentation

technical-documentation scores 91/100 on our quality scale, 361st of 1,153 Content & Media skills we index (top 32%).

Its SKILL.md is 21 KB long, well organised into 17 sections with 1 code example: a thorough specification that gives an agent plenty to work with.

With 2,248 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
17/20
Description
15/15
Adoption
14/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so technical-documentation is actively maintained.
  • Our last check on 2026-10-29 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

technical-documentation compared with similar skills

All 4 of these similar skills score higher than technical-documentation; compare them before choosing.

SkillScoreStarsUpdatedFormat
technical-documentation (this skill)by wondelai912.2k2mo agoSKILL.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Scraplingby D4Vinci100103.6k2d agoMCP Server
crawl4aiby unclecode10087.4k3d agoMCP Server

Frequently asked questions

How do I install technical-documentation?
Run npx skills add wondelai/skills --skill technical-documentation. The install tabs above show the steps for each supported agent.
Which AI agents does technical-documentation work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is technical-documentation safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is technical-documentation still maintained?
The repository was last updated about 2 months ago, so technical-documentation is actively maintained.

name: technical-documentation description: 'Audit, write, and improve developer documentation using Google''s Developer Documentation Style Guide and Technical Writing courses. Use this skill for any documentation work, even when the user names no style guide: "audit our docs", "review this README", "write a README", "getting started guide", "how-to or tutorial", "API reference", "docstrings", "CLI help text", "changelog or release notes", "migration guide", or "our docs are confusing". Also use it when writing docs from code, rewriting a doc for clarity, fixing headings, procedures, or code samples, or enforcing consistent voice and terminology across a docs set — prefer it over editing documentation unaided. Covers reader and doc-type fit, second person and active voice, procedures, headings, lists and tables, code samples and placeholders, link text, notices, the word list, timeless docs, and accessibility. For code comments and naming, see clean-code. For marketing or landing-page copy, see storybrand-messaging.' license: MIT metadata: author: wondelai version: "1.0.0"

Technical Documentation

Audit, write, and improve developer documentation the way Google's technical writers do: start from the reader's task, verify every fact against the code, then apply the style guide in severity order — structure before voice, voice before word choice.

Core Principle

Write for the reader's task, not the product's feature list. Google's guide asks for prose that is conversational but not frivolous, precise, and consistent, because a developer reading docs is trying to get something done, not to admire the product. Two framing rules from the guide shape everything below:

  • Guidelines, not rules. Depart from the guide when doing so improves the content — established domain terminology wins — but stay consistent within the document.
  • Precedence. A project's own style guide comes first, then Google's guide, then Merriam-Webster (spelling), the Chicago Manual of Style (general style), and the Microsoft Writing Style Guide (technical style).

Rules come in two layers. Structural and content rules (headings, procedures, code samples, second person, active voice, timeless docs, accessibility) apply to documentation in any language. Rules tagged [EN] (spelling, serial comma, contractions, the word list) apply only to English text — skip them for other languages, and never translate a document unless asked.

Scoring

Goal: 10/10. Score = number of Quick Diagnostic rows passed (10 rows, 1 point each; the [EN] row auto-passes for non-English docs). Bands: 9-10 = ships as is; 7-8 = word- and voice-level edits only; 5-6 = restructure sections, then re-edit; ≤4 = rewrite from the doc-type skeleton. Blocking findings — wrong or unverifiable facts, a procedure that can't be completed, information that exists only in an image or in an image without alt text — are a separate gate: the doc is not shippable at any score until they're fixed. Report the score, the failed rows, and the exact edits that reach 10/10.

Framework

1. Know the Reader and the Document's Job

Core concept: Every page serves one reader with one task. Name both before writing a word — audience and level, what they'll be able to do afterwards — and pick the document type that fits: tutorial (learn by doing), how-to (accomplish a task), concept (understand), reference (look up), README (orient and start).

Why it works: Readers scan for their task; a page that mixes concept, procedure, and reference forces them to read everything to find anything.

Key insights:

  • Google's Technical Writing course opens a doc with an audience statement and a scope plus non-scope statement — the non-scope rescues readers who are on the wrong page
  • "Before you begin" lists prerequisites before step 1, not inside step 4 (convention)
  • Key points first: the intro states what the reader gets, not the product's history
  • Every procedural page ends with verification ("Confirm that…") and "What's next" (convention)

Applications:

| Context | Application | Example | |---------|-------------|---------| | README | Orient: what it is, who it's for, three-step start, links out | Purpose → install → first run → docs map | | Mixed page | Split concept from procedure into linked pages | "How OAuth works" + "Configure OAuth" | | Tutorial vs how-to | Tutorial teaches one path end to end; how-to assumes context | "Build your first plugin" vs "Add a hook" |

See references/document-types.md when choosing or restructuring a doc type — skeletons for README, getting started, tutorial, how-to, and concept pages, the audience and scope statements, and the self-editing pass for large doc sets.

2. Voice: You, Active, Present, Timeless

Core concept: Address the reader as "you", make the actor of every sentence explicit, describe behavior in the present tense, and write as if the page will be read in five years.

Key insights:

  • "We" hides who acts; "the user" turns the reader into a third party — both weaken an instruction
  • Passive voice is allowed only when the actor is unknown or irrelevant ("The file is encrypted at rest")
  • "Will" belongs only to genuinely later effects: "The server sends an ack", not "will send"
  • Contractions are fine — Google prefers "isn't" over "is not" for negations [EN]
  • Software doesn't want, see, or think: "The API detects", not "the API sees"
  • No "please" (reserve it for asking permission), no "simply / easily / just", no superlatives — if a step is easy, the reader will notice
  • Timeless: cut "currently", "new", and "soon"; never pre-announce unreleased features

Before → after:

  • "Please note that the new dashboard will simply be shown once the user has logged in." → "After you sign in, the dashboard appears."
  • "We recommend that the token is refreshed by the client." → "Refresh the token from the client."

See references/voice-and-words.md when a doc's tone is off or inconsistent — the voice rules with the guide's exact exceptions, inclusive and global-audience language, and the full word list.

3. Sentences and Words

Core concept: Put the condition before the instruction, keep one idea per sentence, and choose the plain word the guide's word list prefers.

Key insights:

  • "To delete the document, click Delete" — readers decide whether a step applies before they act, not after
  • Spell out an abbreviation on first use with the short form in parentheses; skip only universally known ones (URL, HTML)
  • Latin abbreviations translate and scan poorly: "for example", not "e.g."; "that is", not "i.e."; omit "etc." or finish the list [EN]
  • "can" = ability, "may" = permission, "might" = possibility [EN]
  • Word list samples [EN]: sign in (not log in) · set up as a verb · lets you (not allows you to) · through or by using (not via) · after (not once) · use (not leverage or utilize) · checkbox · email
  • Jargon is fine for the stated reader and a defect for anyone else — define it or link it

Before → after:

  • "Click Save in order to persist the settings once you are done, i.e. when all fields are filled." → "After you fill in all fields, click Save."
  • "The CLI utilizes the GCP SDK (e.g. for auth)." → "The CLI uses the Google Cloud SDK, for example for authentication."

See references/voice-and-words.md when auditing word choice — the word list table (avoid → use → why), abbreviation rules, and modal verbs.

4. Structure: Headings, Lists, Tables, Notices

Core concept: Structure is the reader's map. Headings in sentence case read as a table of contents; lists carry parallel items introduced by a full sentence; tables have header rows; notices are rare and mean something.

Key insights:

  • Task headings are bare imperatives ("Create an instance"); concept headings are noun phrases ("Instance lifecycle"); no "-ing" headings
  • A list needs an introductory sentence ending in a colon, and every item in the same grammatical form; numbered only when order matters
  • Description lists (term → definition) beat two-column tables for paired data
  • Tables: header row, an intro sentence, no merged or empty cells — screen readers depend on it
  • Note = useful but optional; Caution = proceed carefully; Warning = harm or irreversible loss. Don't stack them; one per section is a practical ceiling (inferred)
  • Cross-references say "see", never "above" or "below" — pages reflow and get translated
  • Link text names the target ("see Configure a custom domain"), never "click here"
  • Alt text states the image's purpose; information must never live only in a picture

Applications:

| Context | Application | Example | |---------|-------------|---------| | Wall-of-text page | Insert a task heading wherever the task changes | "Install", "Configure", "Verify" | | Three stacked notes | Fold two into body text; keep the one that changes behavior | One Caution about data loss | | Options table | Header row + intro sentence + parallel cell phrasing | "The following flags control output:" |

See references/structure-and-formatting.md when fixing page structure — heading, list, table, notice, cross-reference, link-text, image, number, and date rules with before/after pairs.

5. Procedures and Code

Core concept: A procedure is a numbered list of single imperative actions, each stating where to act and what to expect. Code is set in code font, introduced by a sentence ending in a colon, and uses placeholders the reader can't mistake for literals.

Key insights:

  • One action per step; "Optional:" prefix for optional steps; a single step is a bullet, not "1."
  • Sub-steps run a, b, c; document the shortest path, not every alternative
  • UI element names in bold, matching on-screen casing; click for a mouse, tap for touch, select when device-agnostic
  • Code font for filenames, paths, commands, flags, parameters, and values — not for product names
  • Placeholders are ALL_CAPS_WITH_UNDERSCORES, never <your-key> or YOUR_API_KEY, and are explained right after the sample ("Replace PROJECT_ID with…")
  • Command syntax: [optional], {a|b} for exclusive choices, ... for repeatable arguments
  • Samples are runnable, minimal, wrapped at 80 characters, and show the expected output

Before → after:

  • "Run the command below with your key: shipit deploy --key=<your-key>" → "To deploy, run the following command:" → fenced shipit deploy --key=API_KEY → "Replace API_KEY with the key from the Settings page."
  • "1. You should now click on the Deploy button to deploy." → "1. Click Deploy. The status changes to Deploying."

See references/procedures-and-code.md when writing steps or samples — the full procedure rules, UI-element and device verbs, code-in-text, placeholder, command-line syntax, and the sample-code quality checklist.

6. Reference Docs: API, Docstrings, CLI Help

Core concept: Reference text is descriptive, complete, and formulaic on purpose — readers look things up, so every entry must exist and read the same way.

Key insights:

  • Document every public class, method, field, constant, and enum value; a missing entry reads as "unsupported"
  • Open method descriptions with the category verb: "Gets the…", "Sets the…", "Checks whether…", "Creates a…", "Returns…" — never "This method…"
  • Non-boolean parameters start "The…" or "A…"; booleans read "If true, … If false, …" (action) or "True if …; false otherwise" (state)
  • Document return values and exceptions ("Thrown when…") for every method that has them
  • A deprecated element names its replacement in the first sentence
  • CLI --help (convention — Google has no --help page): usage line in [optional] syntax, one-line synopsis, every flag described with the same p

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars2.2k
CategoryContent
Updated2mo ago
Forks228

Languages

Shell

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions