| name | tech-tutorial |
| description | Plans, drafts, and refines technical tutorials for developers. Use when writing step-by-step guides or getting-started walkthroughs backed by working code. |
| globs | **/*.md |
| alwaysApply | false |
| category | artifact-generation |
| tags | ["tutorial","technical-writing","code-examples","developer-docs","getting-started"] |
| tools | [] |
| complexity | medium |
| model_hint | standard |
| estimated_tokens | 2800 |
| progressive_loading | true |
| modules | ["modules/outline-structure.md","modules/code-examples.md","modules/progressive-complexity.md"] |
| dependencies | ["scribe:slop-detector"] |
Tech Tutorial
A good technical tutorial has one goal: move a reader from not knowing
how to do something to being able to do it.
That requires working code, concrete steps, and honest acknowledgment
of where things go wrong.
This skill guides you through outlining, drafting, and verifying a
tutorial that meets that standard.
When To Use
- Writing a getting-started guide for a library, CLI tool, or API
- Creating a step-by-step walkthrough that readers follow at a terminal
- Explaining a technical concept through a hands-on exercise
- Producing a how-to that complements API reference documentation
When NOT To Use
- Generating API reference docs (use
scribe:doc-generator)
- Cleaning up existing prose (use
scribe:slop-detector)
- Producing high-level architecture overviews without runnable steps
- Writing conceptual essays without hands-on components
Methodology
Step 1: Scope and Audience
Before writing a single line, answer these questions:
- Who is this for? (experience level, assumed prior knowledge)
- How many readers? How often will each one read it?
- What will they build or accomplish by the end?
- What is the one sentence they must walk away with?
(the thesis, not the topic)
- What is the single prerequisite the reader must have installed?
- What is explicitly out of scope?
Write these answers down as a header block in the draft.
If you cannot answer the "what will they accomplish" question
in one sentence, the scope is too broad. If you cannot state
the thesis in one sentence, the tutorial is not ready to draft.
The audience size and read frequency feed the reader-time
budget (see scribe:slop-detector module document-economy.md).
A tutorial that 500 developers will read once is a 40-hour
reader-budget asset. Spend the writing time accordingly.
Step 2: Outline
Load: @modules/outline-structure.md
Produce a section-by-section outline before drafting prose.
Each section entry must include a one-line description of what
the reader does or learns in that section.
See the outline module for the standard section order and
length targets per section type.
Step 3: Draft Code Examples First
Load: @modules/code-examples.md
Write the code before the prose.
Each snippet must run against a real environment before it
appears in the tutorial.
Annotate only the non-obvious lines.
See the code examples module for formatting and error-handling rules.
