Tutorial writing
Skill Amey-Thakur/AI-SKILLS/skills/documentation/tutorial-writing
Plug-and-play skills and prompts for every AI coding agent
npx -y skills add Amey-Thakur/AI-SKILLS --skill tutorial-writingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Write tutorials that take a learner from zero to a working result through tested steps with checkpoints and recovery. Use when creating learning-oriented documentation or onboarding guides.
SKILL.md
3.3 KB, as published. Nobody here has run it
Tutorial writing
A tutorial is learning-oriented: its job is to give a beginner a successful first experience, building confidence through a working result. It is not reference (complete) or how-to (goal-oriented for someone who already knows the domain); confusing the genres produces tutorials that overwhelm and reference that cannot teach.
Method
- Define the concrete end state. "By the end you will have a working X that does Y": one specific, achievable, satisfying result. A tutorial without a clear destination wanders; the learner needs to know where they are going and to feel they arrived (see mvp-scoping's aha-moment, applied to learning).
- Make every step do-able and verified. Exact commands and code (copy-pasteable, tested in CI: see docs-as-code), and after each meaningful step, what the learner should see ("you should now see X"): so they confirm they are on track before continuing (the runbook-writing verification rule, for learners). A step that silently fails leaves the beginner stuck with no idea where.
- Minimize prerequisites and cognitive load. Assume as little as possible, install what is needed inline, and introduce one new concept at a time (see cognitive-load): a tutorial that requires the reader to already understand half the system is not a tutorial. Defer the "why" and the alternatives; the learner wants to succeed first, understand later.
- Guarantee it works, keep it narrow. The tutorial's golden path must work every time (this is why examples are tested: a failing tutorial destroys the beginner's confidence, not just their afternoon); resist the urge to show every option or handle every case: those belong in reference and how-to guides (see docs-information- architecture). One path, working, start to finish.
- Provide recovery for the likely failures. Where learners commonly get stuck (a permission error, a missing dependency), a short "if you see X, do Y": anticipate the three most common failure points and catch them, because a stuck beginner with no recovery path abandons the tool, not just the tutorial.
- End with orientation, not a cliff. Recap what they built, and point to next steps (the how-to guides and reference for going further: see readme-writing's linking): the tutorial's success is a launchpad. Leaving the learner at a working result with no direction wastes the momentum you just built.
Boundaries
- A tutorial is not comprehensive; it deliberately omits options, edge cases, and alternatives to keep the learner succeeding (see reference and how-to for those: docs-information-architecture's Diataxis split). Padding it toward completeness ruins it.
- Tutorials are expensive to keep working (every dependency and API change can break the golden path); test them in CI and budget maintenance, or they rot into confidently wrong instructions (see docs-maintenance).
- One tutorial cannot serve every skill level; a beginner tutorial and an advanced walkthrough are different documents for different readers.