Authoring reference
Skill pkloehn1/techdocs-authoring/skills/authoring-reference
Use when writing, structuring, or reviewing any README, how-to, tutorial, reference, ADR, runbook, release notes, or AI-agent-readable docs. Reference knowledge and an authoring playbook for technical documentation: picking a canonical style guide, the Diataxis four-mode model (tutorial/how-to/ reference/explanation), copy-paste templates and reviewer checklists, single-sourcing and content reuse, a writing process that leads with the bottom line, and writing docs that serve both humans and AI agents.From its SKILL.md
npx -y skills add pkloehn1/techdocs-authoring --skill authoring-referenceAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
5.8 KB, as published. Nobody here has run it
Documentation authoring reference
Reference and playbook for writing and reviewing technical documentation. This file is the index; load a reference file only when a task needs it (progressive disclosure).
- Pick a canonical style guide and the highest-agreement mechanical rules (voice, mechanics, screenshots/media) → references/style-guide.md
- The Diataxis four-mode model and how to choose one mode per page → references/doc-types-and-diataxis.md
- Copy-paste section skeletons + reviewer checklists for the seven core artifacts (README, how-to, tutorial, reference, ADR, runbook, release notes) → references/templates-and-checklists.md
- When and how to reuse content (single-sourcing, DITA tiers, change-impact) → references/single-sourcing-and-reuse.md
- The authoring pipeline — outline, draft, then a separate editing pass → references/writing-process.md
- Writing docs that serve both humans and AI agents → references/docs-for-humans-and-agents.md
Operating principles
- Name the audience and the single goal first. Decide who reads this and what they must be able to do afterward before writing a sentence.
- Lead with the bottom line. Open with the outcome, recommendation, or required action; put warnings before background.
- One Diataxis mode per page. Each doc is a tutorial, how-to, reference, or explanation — never a blend. Split a doc that mixes modes.
- Adopt, don't invent, a style guide. Pick one canonical guide by audience; extend it with a thin local layer; never blend two guides mid-document.
- Structure before prose. Fix layout, headings, and task flow first; edit for clarity, conciseness, and correctness in a separate pass.
- Reuse with intention. Single-source only when multiple outputs or audiences justify it; otherwise stay linear. Link to one authoritative source rather than copy.
- Verify by use. A doc is done when someone who did not write it can complete the task; tie factual claims to evidence.
Universal invariants
These are the canonical rules. Other files and the technical-writer agent
reference this list rather than restating it.
- Modes never mix in one page. A tutorial that drifts into reference tables or background theory is two documents; reviewers reject cross-quadrant content.
- Reference describes; it never instructs or explains. How-tos and tutorials instruct; explanation gives the "why." Keep them apart.
- Every how-to and runbook ships a verification step — how to confirm the goal was achieved — and every runbook also ships rollback and escalation.
- ADRs are immutable once accepted. You supersede an ADR with a new one and cross-link them; you do not edit the decided record.
- Cross-guide-safe defaults: second person, active voice, present tense, sentence-case headings, the serial comma, descriptive link text (never "click here").
- Don't duplicate; link. One authoritative location per fact or procedure;
no version-suffixed copies (
-v2,-new,-legacy).
Boundary: craft vs. repo enforcement
This skill carries portable writing craft. Your repository owns its enforcement — line-length limits (e.g. an MD013 character cap), numbered- heading validation, diagram linting, pre-commit / CI lint wiring, and the actual repo paths. Follow your repo's enforced limits where they exist; this skill defers the numbers and the tooling to it and never restates them. Where a mechanical rule here overlaps a craft principle your repo already adopted (Strunk-style economy, a grade-9 readability target, single-source-of-truth), treat them as the same shared baseline, not competing rulesets.
Quick entry point
Starting or reviewing a doc:
- Classify. Name the audience, the single goal, and the Diataxis mode.
- Template. Pull the matching skeleton + reviewer checklist from references/templates-and-checklists.md.
- Draft, then edit. Outline and draft; then run the editing pass (clarity, conciseness, correctness) from references/writing-process.md as a separate step.
- Verify. Run the project's Markdown linters (
pre-commit,markdownlint, orvale) to catch line-length and other findings, then confirm the reader can complete the task, every link resolves, and the page holds exactly one mode.