stacklok · jbeda · Sep 24, 2026 · Sep 24, 2026
@@ -8,6 +8,18 @@ origin of borrowed text is auditable.
 recording the upstream source, the commit it was taken at, its licence, and
 what was changed. Skills written from scratch for modelith don't need an entry.
 
+## tech-writer
+
+- **Upstream:** [`stacklok/mecatl`](https://github.com/stacklok/mecatl),
+  `.claude/skills/tech-writer/`; copied through local checkout
+  `../mecatl-clean`.
+- **Taken at:** skill commit `33a3747d9008691d4d51a872c9e82c050c43fafa`
+  (2026-09-23), from checkout `d96de1fb6f40a713754dd3c65da8bcecf45a920b`.
+- **Licence:** Apache License 2.0; see the upstream checkout's `LICENSE`.
+- **Changes:** adapted the model-specific references to point at
+  `docs/_docs-conventions.md`, `CLAUDE.md`, and `.claude/rules/`; retained the
+  upstream body and `references/` directory otherwise.
+
 ## grilling
 
 - **Upstream:** [`mattpocock/skills`](https://github.com/mattpocock/skills),

@@ -0,0 +1,84 @@
+---
+name: tech-writer
+description: >
+  Use when writing or substantively editing user-facing documentation: drafting a new page, rewriting or restructuring an existing one, adding a major section, or turning engineering material (PR descriptions, specs, release notes, rough notes) into docs. Writes clear, focused technical documentation following the Diataxis framework and modelith's local documentation conventions. Use it even when the request doesn't mention writing quality; it governs how documentation gets written. Not for editorial review of finished work.
+---
+
+# Technical writing
+
+Write documentation as a senior technical writer: clear, accurate, and focused on what the reader needs to accomplish. Every page has one primary reader need, and the discipline of this skill is deciding which one before writing a word, then keeping that purpose clear. Brief supporting context from another mode is often useful; it should help the reader without competing with the page's primary purpose.
+
+Everything in this skill and its references is guidelines, not rules. Each one explains its reasoning so you can depart from it when doing so genuinely improves the content for the reader, knowing why you're departing. What's never optional is the judgment itself: a rule followed into an absurd result is as much a failure as a rule ignored.
+
+## Canonical sources
+
+Don't duplicate guidance; read it from where it lives:
+
+1. **The local [style guide](references/style-guide.md)** provides prose and
+   style guidance.
+2. **[`docs/_docs-conventions.md`](../../../docs/_docs-conventions.md)** owns
+   public-documentation placement, links, and verification for modelith.
+3. **`CLAUDE.md` and `.claude/rules/`** own contributor-documentation and
+   repository-process guidance.
+4. **The mode references** in [`references/`](references/) provide Diataxis
+   discipline and write-time anti-patterns.
+
+## Workflow
+
+1. **Classify.** Use the compass below to decide the page's primary mode. Include brief in-situ context from another mode when it helps the reader understand or complete the task. Split supporting material into a separate page only when it warrants a full discussion or workflow, or when it would compete with the page's primary purpose. Keep the modes distinguishable without creating a separate page for every type of content.
+2. **Place.** For public documentation, follow
+   [`docs/_docs-conventions.md`](../../../docs/_docs-conventions.md). For
+   contributor documentation, follow `CLAUDE.md` and the applicable
+   `.claude/rules/` guidance. Update the owning page; do not append the same
+   feature narrative to several pages. Create a page only for a distinct reader
+   need.
+3. **Read.** Read the reference file for your mode, plus [the write-time anti-patterns](references/anti-patterns.md), plus the style guide sections your task touches. For a new page, also skim 1-2 existing pages of the same type in the same section so the new page reads like a sibling, not a transplant.
+4. **Draft.** Outline first, weighting coverage by real-world use: the workflow most readers came for gets the worked example and the narrative; situational options get a sentence and a reference link; esoteric knobs stay in reference (see "Proportionality" in the anti-patterns file). Then write for the reader described in the mode reference, stating the most important thing first on the page and in each section.
+5. **Self-check.** Before presenting the draft, reread it against the anti-patterns file and the mode's "keep out" list. Cut what fails. For substantial new content, use an independent editorial review when available; for small edits, the self-check is enough.
+
+## The compass: classifying content
+
+Two questions determine the mode: does the content inform the reader's _action_ (doing) or _cognition_ (understanding), and does it serve the _acquisition_ of skill (learning) or the _application_ of skill (working)?
+
+| Content...        | ...serves skill... | Mode        | It is...     |
+| ----------------- | ------------------ | ----------- | ------------ |
+| informs action    | acquisition        | tutorial    | a lesson     |
+| informs action    | application        | how-to      | a recipe     |
+| informs cognition | application        | reference   | a map        |
+| informs cognition | acquisition        | explanation | a discussion |
+
+A quick tiebreaker: ask what the reader is doing when they open the page. Learning by following along means tutorial. Getting a real task done means how-to guide. Looking something up means reference. Trying to understand why or how something works means explanation.
+
+## The four modes
+
+- **Tutorial** - a guided lesson where you take responsibility for the reader's success. Quickstarts and end-to-end getting-started pages. Read [the tutorial guidance](references/tutorials.md).
+- **How-to guide** - a recipe for a competent user with a real task. Usually the bulk of a documentation set: task-oriented guides and integration walkthroughs. Read [the how-to guidance](references/how-to-guides.md).
+- **Reference** - neutral, complete description of the machinery: CLI commands, API and schema specs, configuration fields, compatibility tables. Often auto-generated; check the project's rules before touching generated files, since fixes usually belong upstream. Read [the reference guidance](references/reference.md).
+- **Explanation** - understanding-oriented discussion of concepts, background, and design reasoning. Concept pages and product introductions. Read [the explanation guidance](references/explanation.md).
+
+## Reference files
+
+| When you are...                                | Read                          |
+| ---------------------------------------------- | ----------------------------- |
+| Writing or editing a tutorial or quickstart    | [Tutorials](references/tutorials.md)             |
+| Writing or editing a how-to guide              | [How-to guides](references/how-to-guides.md)      |
+| Writing or editing reference material          | [Reference](references/reference.md)              |
+| Writing or editing concept/explanation content | [Explanation](references/explanation.md)          |
+| Drafting anything (always, before self-check)  | [Write-time anti-patterns](references/anti-patterns.md) |
+| Checking style, structure, or terminology      | [Style guide](references/style-guide.md)           |
+
+## Self-check
+
+Before presenting a draft, verify:
+
+- [ ] The page has a clear primary mode. Supporting context from another mode helps that purpose; material that warrants a full discussion or competing workflow was split out and linked.
+- [ ] The most important point leads the page and each section; no buried ledes.
+- [ ] Coverage is proportional to real-world use: the common workflow carries the page, situational options get a sentence and a reference link, and nothing is documented just because it exists.
+- [ ] Every factual claim about behavior, flags, fields, or defaults was verified against source, specs, or generated reference docs, not recalled from memory. Living docs describe implemented behavior, not merely an approved plan.
+- [ ] Outdated and duplicate text was replaced or deleted. Only unique, verified knowledge was migrated; implementation chronology stays in PRs/Git rather than a catch-all notes page.
+- [ ] Code examples work as written: real values for fixed things, `<ALL_CAPS>` placeholders for reader-supplied values, reserved domains (`example.com`) in URLs.
+- [ ] The draft passes the anti-patterns file: no changelog framing, negative restatement, redundant admonitions, hedging, listitis, or em-dash rhythm.
+- [ ] Front matter (where the site uses it) has `title` and a `description` whose first 70 characters stand alone.
+- [ ] How-to guides and tutorials end with the project's closing-section pattern (for Stacklok docs: Next steps, then Related information, then Troubleshooting, in that order, as applicable).
+- [ ] The page is reachable: a navigation/sidebar entry plus inbound links from related pages.
+- [ ] Terminology matches the style guide's word list.
@@ -0,0 +1,64 @@
+# Write-time anti-patterns
+
+[Technical writing skill](../SKILL.md)
+
+These are the habits that most often degrade documentation drafts. Read this list before drafting and again during self-check. Most of them are natural tendencies of LLM-generated prose, which is exactly why they need active resistance at write time rather than cleanup at review time.
+
+Apply the same catalog when reviewing documentation. When a new recurring
+pattern warrants repository guidance, update this file rather than creating a
+second review-only copy.
+
+## Proportionality
+
+The deepest form of over-documentation isn't repetition; it's flat coverage. Fix it at the outline stage, before any prose exists.
+
+**Flat option coverage.** A guide that gives every option, flag, and field equal billing reads like a control panel, not a recipe. The reader can't tell the paved road from the escape hatch, and the workflow most readers came for drowns in the long tail. Budget coverage by the share of readers who will actually use something: the common path gets the worked example and the narrative; a legitimate but situational option gets a sentence naming the situation and a link to reference; an esoteric knob gets nothing in the guide at all, because the reference already describes it and the readers who need it know to look. Two tests for any option you're about to document in a guide:
+
+- If you were helping a colleague do this task at their desk, would you bring this option up unprompted? If not, it doesn't belong in the guide's main path.
+- Does the option change what the reader _does_, or just what a value _is_? Changed workflows can earn guide coverage; values that exist belong in reference.
+
+**Completeness reflex.** The instinct that a feature isn't fully documented until every capability appears in a guide somewhere. Completeness is reference's job, and the generated reference already provides it. A guide that covers less but is followable end to end serves more readers than one that covers everything. When an engineer's PR or spec lists ten configuration fields, that's an input inventory, not an outline; the outline comes from what readers are trying to do.
+
+## Rhythm and punctuation
+
+**Em dashes, and their disguises.** Never use `—` or `–`. Just as important: don't mechanically swap in a spaced hyphen or a comma while keeping the same "clause - punchy addendum" rhythm; that cadence reads as AI-generated even with the character fixed. Actually restructure: split the sentence, subordinate the clause, or cut the addendum. Spaced hyphens are only for list-style separators ("Topic - description" entries).
+
+**Symmetric triads and balanced pairs.** "Fast, secure, and reliable." "Not just X, but Y." These rhetorical rhythms are filler in technical prose. If the three adjectives each carry a verifiable fact, keep the facts and lose the drumbeat; usually only one of them matters.
+
+## Framing
+
+**Changelog framing.** "Starting in v0.41", "previously", "now supports", "moved from X to Y". Docs state current behavior; release notes tell the story of change. This leaks in most when drafting from a PR or release diff: you're looking at a delta, but the reader needs a state. Write the page as if the behavior had always been this way. (Narrow exception for breaking changes: see "Document current behavior" in the style guide.)
+
+**Negative restatement.** "Uses X, not Y." "Don't point it at the public endpoint." If the negation carries no new fact, cut it; if it carries one, fold that fact into the positive statement ("point it at the internal endpoint, which...").
+
+**Buried lede.** The key fact ("this is automatic", "this requires Kubernetes") arrives after paragraphs of preamble. Lead every page and every section with the thing the reader most needs; the background can follow for those who keep reading.
+
+**Dramatized limitations.** State gaps and limitations accurately and neutrally ("the UI doesn't yet expose this setting; use the CLI"), without apology, alarm, or spin in either direction.
+
+**Marketing adverbs.** "Simply", "easily", "seamlessly", "powerful". If it's simple, the short instruction demonstrates that; saying so just mocks the reader for whom it isn't.
+
+## Substance
+
+**Hedging.** "May", "might", "could potentially", "should generally". Look up what actually happens and state it. If behavior is genuinely conditional, name the condition instead of hedging.
+
+**Hedged lists.** "Clients such as VS Code and Cursor..." when the supported set is knowable. State the full list or link to the canonical reference (usually a compatibility page); "such as" invites the reader to guess.
+
+**Over-explaining.** Restating what a command obviously does, defining concepts the audience (developers and DevOps professionals) already has, narrating the obvious consequence of the previous sentence. Trust the reader and cut.
+
+**PR jargon leak.** "Consumers", "surface area", "wire up", "shapes". These come from the engineering artifact you're drafting from, not the reader's vocabulary. Name the actual components, fields, and values.
+
+**Unverified facts.** Never write a flag name, field, default, or version constraint from memory. Verify against source, the schema, or the generated reference, and cite where it came from when presenting the draft.
+
+**Placeholder examples.** `my-server`, `example-org`, `foo` where a real value exists. Use real values for fixed things (commands, image names, registry servers), `<ALL_CAPS>` for values the reader supplies, and reserved domains (`example.com`) in URLs, never real domains.
+
+## Structure
+
+**Listitis.** Bullets are for genuinely enumerable items. Consecutive single-sentence bullets that each begin with a bolded phrase are prose wearing a costume; readers can't follow an argument chopped into fragments. Write connected paragraphs for reasoning and comparisons (or a table when the items are truly parallel facts).
+
+**Mirror-image sections.** "When to use X" followed by "When to use Y" that just inverts it. Write the comparison once, as a table or one honest paragraph of trade-offs.
+
+**Admonition abuse.** An admonition must add information beyond the adjacent prose. If a note restates or negates what the paragraph just said, cut it. If it contains the only documentation of a feature, a worked example, or a full config block, it isn't a note; promote it to a section with a heading. One or two admonitions per page is the norm.
+
+**Heading proliferation.** A heading per paragraph makes a page read like an outline and bloats the ToC. Sections need enough substance to deserve a name; merge stubs.
+
+**Duplicated content.** Detailed content lives in exactly one place; other pages link to it with a line of context. If you're pasting a paragraph you wrote for another page, stop and link instead.
@@ -0,0 +1,31 @@
+# Writing explanation
+
+[Technical writing skill](../SKILL.md)
+
+Explanation is a discussion. The reader is away from the keyboard, or at least away from the task, and wants to deepen their understanding: how does this work, why is it designed this way, how does it relate to the alternatives? Explanation is the mode that serves study rather than work, and it's the only mode where context, background, opinion, and trade-offs belong.
+
+Explanation typically lives in a concepts section (protocol primers, architecture overviews, security frameworks) and in each product section's Introduction page, which explains what the product is and who it's for.
+
+## Principles
+
+**Answer "why", not "how".** Explanation provides the reasoning, history, constraints, and mental models behind the machinery: why ToolHive runs MCP servers in containers, how the authorization pieces fit together, when vMCP makes sense. The moment you're writing numbered steps, you've left the mode.
+
+**Bound the topic.** A useful test: the page should make sense with "About" in front of its title ("About network isolation"). If it wouldn't, the scope is fuzzy. Say early what the page covers, and keep it there; explanation has no natural task boundary, so unbounded pages sprawl.
+
+**Make connections.** Explanation earns its keep by joining things: how a feature relates to its neighbors, to the broader ecosystem, to what the reader already knows from elsewhere. Comparisons, context, and even relevant history (why the ecosystem settled on a pattern) are welcome here in a way they're welcome nowhere else. Weigh that against the "document current behavior" rule in the style guide: product-version changelog narration is still out, but design rationale and ecosystem background are fair game.
+
+**Discuss trade-offs and admit alternatives.** Explanation is where "when to use X vs. Y" content belongs, with honest weighing rather than a sales pitch. State limitations accurately and neutrally; don't dramatize them, and don't paper over them.
+
+**Opinion is allowed; keep it justified.** Perspectives and recommendations are legitimate here ("for production deployments, the operator is the better fit because..."), provided the reasoning comes with them.
+
+**Serve understanding, not completeness.** Explanation doesn't need to mention every field or cover every case; that's reference's job. Choose the details that build the mental model and link out for the rest.
+
+## Keep out of explanation
+
+- Step-by-step instructions (link to the how-to guide)
+- Exhaustive technical description, field lists, option tables (link to reference)
+- Anything the reader must do; explanation should be safely skippable by someone who just wants to get the task done
+
+## Structure
+
+Explanation is prose-first. Headings mark the major facets of the topic, and paragraphs, not bullet fragments, carry the reasoning; connected argument is the whole point of the mode, and bullets break the connections. Diagrams (Mermaid) help when the relationships are structural. Close with Next steps or Related information pointing to the quickstart or guides where the reader applies the understanding.