spb/ultra-sharp-agent-skills Public

1---2name: writing-tutorials3description: Writes step-by-step tutorials and how-to guides where every step has a verifiable checkpoint, full commands, and expected output. Use when the user asks to write a tutorial, a how-to guide, a getting-started guide, a walkthrough, or onboarding steps for learners. Do not use for reference documentation, conceptual overviews and READMEs, or API endpoint docs — separate skills cover those.4---56<!--7Author: Simon-Pierre Boucher8Contact: contact@spboucher.ai9-->1011# Writing Tutorials1213## When to use / when NOT to use14- **Use for:** tutorials, how-to guides, getting-started walkthroughs, workshop material — content a learner follows top to bottom.15- **Do NOT use for:** reference docs (writing-api-documentation), conceptual overviews/READMEs (writing-technical-documentation), or blog posts (writing-blog-posts).1617## House rules18191. **State the destination upfront:** end result, prerequisites (with versions), and honest time estimate — before step 1.20   - ✅ "By the end you'll have a deployed webhook receiver. Prerequisites: Python 3.12, an ngrok account. Time: ~20 minutes."21   - ❌ Diving into `mkdir project` with no destination stated.22232. **One path only.** No forks, options, or "alternatively…" mid-tutorial; link alternatives at the end.24   - ✅ "We'll use SQLite. (Using Postgres instead? See the appendix link at the end.)"25   - ❌ "You can use SQLite, Postgres, or MySQL here — configure accordingly."26273. **Every step ends with a verifiable checkpoint.**28   - ✅ "Run `curl localhost:8000/health` — you should see `{"status":"ok"}`."29   - ❌ Three file edits in a row with no way to know they worked.30314. **Full commands, full expected output.** Never `cd <your-project>`; never truncate output the learner must compare against.32   - ✅ The exact command plus the exact lines it prints.33   - ❌ "Run the usual migration commands."34355. **Never skip steps that "everyone knows."** Activating the virtualenv, exporting the variable, saving the file — write them.36   - ✅ "Save the file, then in the same terminal run…"37   - ❌ "Simply configure your environment."38396. **Troubleshoot the 3 most likely failures inline**, at the step where they occur — not in a distant appendix.40   - ✅ "If you see `Address already in use`, another process holds port 8000: run `lsof -i :8000`…"41   - ❌ A generic "Troubleshooting" section listing every possible error.42437. **End with "what you built + where to go next":** recap the result and give 2–3 concrete next links.4445## Workflow46471. Do the task yourself start to finish; record every command, output, and mistake you hit (mistakes become inline troubleshooting).482. Write the header: end result, prerequisites with versions, time estimate.493. Convert your recording into numbered steps, each with command → expected output → checkpoint.504. Add inline troubleshooting for the 3 most likely failures at the exact steps they occur.515. Validate: replay the tutorial verbatim in a clean environment (fresh directory/venv/container); any deviation between the doc and reality is a bug — fix it and replay until it runs clean.5253## Edge cases54- **Can't provide a clean environment for replay** → state the tested environment explicitly ("Tested on macOS 15, Python 3.12.4") and flag untested paths.55- **Long tutorial (over ~15 steps)** → split into parts, each part ending at a working state a learner can stop at.56- **Steps involving paid/external services** → say the cost and offer the free-tier route as the single main path.5758## References59Extended before/after examples: see [references/examples.md](references/examples.md).60