A template defines the starting structure of a page. Use it for information that belongs in most pages of a particular kind. A writing guide explains how to write that information.
Start with a reader need
Choose the page's purpose before choosing headings. A how-to helps a reader complete a task; a reference supports lookup; an explanation builds understanding; a tutorial teaches through a guided exercise. Keep distinct needs on separate pages when combining them makes either harder to use.
For an ingredient, define one reusable action, its inputs, and its success check. For a recipe, give the complete ordered procedure and recovery advice. A cookbook helps readers choose among recipes. These structures support reuse without making readers assemble their own instructions.
Make prompts actionable
A useful placeholder asks for specific missing information: prerequisites, a tested command, expected output, or a recovery action. Avoid vague prompts such as “add useful details.” Tell the agent to flag missing evidence instead of filling gaps with plausible facts.
Keep required sections small. Make optional sections clearly optional, and provide a reviewed example outside the template. A copied example's technical details are not evidence for a different feature.
Keep structure and checks separate
Shoalrun's template overrides control scaffold text. They do not automatically change configured lint rules. Match the template to your page-type conventions and configure checks explicitly.
Review a template by drafting several real pages with it. Remove sections authors repeatedly leave empty, and add prompts where readers repeatedly lack information. Check both HTML and Markdown so essential instructions survive every representation.