# Tutorial Writing

> Write task-focused tutorials for developers, users, maintainers, or operators. Use when Codex is asked to create a walkthrough, quickstart, how-to, learning path, or step-by-step guide that leads to a verified outcome.

- Skill: `gabrielmoreira/tutorial-writing` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/tutorial-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/tutorial-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/tutorial-writing

---


# Tutorial Writing

## Core Workflow

1. Identify the learner, starting point, outcome, prerequisites, and time
   budget.
2. Choose one concrete task and avoid turning the tutorial into a full
   reference manual.
3. Write steps that explain what to do, why it matters, and how to verify the
   result.
4. Include expected output, common failure points, and recovery notes where
   useful.
5. Link to reference docs for deeper details instead of overloading the path.
6. End with a finished artifact, working state, or next practical task.

## Safety Rules

- Do not include unverified commands or screenshots as proof.
- Do not ask users to paste secrets into examples.
- Do not hide destructive or cost-incurring steps inside a tutorial.

## Deliverable Shape

For tutorials, provide:

- Goal and audience
- Prerequisites
- Starting state
- Step-by-step walkthrough
- Expected result
- Verification checks
- Troubleshooting notes
- Next task

## References

- Read `references/tutorial-writing-checklist.md` when writing or reviewing a
  tutorial or quickstart.