How-To Guide Template

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/templates/how-to.md
Description	Not specified

Source Content

How-To Guide Template

A recipe for a reader who already has the basics and wants a specific goal done. Diátaxis mode: how-to — start from the goal, not from theory.

Skeleton

# How to {{accomplish a specific goal}}

{{Two-person story first — one or two sentences: "Jack followed the old
wiki page and lost the afternoon. Jill used this recipe and was done by
standup." Then the goal in one sentence and who this is for.}}

## Before you start

{{Prerequisites; required access; assumptions — one per bullet.}}

## Steps

1. {{Action and the expected result.}}
2. {{Next action.}}
3. {{Verify: "you should see…".}}

## If it goes wrong

{{Open the section with a two-person story: "Jack ran step 2 without the
flag and the deploy hung. Jill added `--wait` and it finished clean." Then
the fix for each common failure, one heading or bullet per failure.}}

## The useful ending

{{One or two sentences, after everything above: what each person from the
opening walked away with, now that this is written down.}}

Rules for this template

• Number the steps; each step is one action with its expected result.
• If the steps branch (“if staging, do X; if prod, do Y”), draw the branch as a Mermaid flowchart per ../mermaid.md instead of nesting prose.
• Flags, env vars, and key: value settings each get their own line.
• The “If it goes wrong” section is mandatory — a how-to without failure modes is half a how-to.
• Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
• Reminders: story, own line per person · useful ending.
• Format: short paragraphs · lists and tables · diagram + “what to notice”.