What it does
Writes or audits a teaching tutorial for a developer product - one new concept per step, checkpoints the learner can verify and resume from, guidance that fades, troubleshooting hooks, and a demonstrable skill at the end
Skills ZICQ category:Media developer-tutorial
Writes or audits a teaching tutorial for a developer product - one new concept per step, checkpoints the learner can verify and resume from, guidance that fades, troubleshooting hooks, and a demonstrable skill at the end. Use whenever the user mentions a tutorial, a build-along or hands-on guide, a "learn X by building Y" article, a workshop or lab handout, a developer course lesson, or says nobody finishes their tutorial - even if they just say "write a guide that teaches this". Do NOT use for a zero-to-first-success quickstart (samber/developer-relations-skills@developer-quickstart-guide) or a video script (samber/developer-relations-skills@technical-video-script).
Official URL:skills.sh
Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.
Writes or audits a teaching tutorial for a developer product - one new concept per step, checkpoints the learner can verify and resume from, guidance that fades, troubleshooting hooks, and a demonstrable skill at the end
ever the user mentions a tutorial, a build-along or hands-on guide, a "learn X by building Y" article, a workshop or lab handout, a developer course lesson, or says nobody finishes their tutorial - even if they just say "write a guide that teaches this". Do NOT use for a zero-to-
Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Developer Tutorial; Scope check; Interview; Workflow; Concept ladder; Checkpoints. It includes spec-recommended sections: step-by-step instructions.
File analysis: besides SKILL.md, the body references references/published-findings.md, references/worked-examples.md, references/tutorial-outline-template.md, references/verification-protocol.md. Those resources load on demand.
Developer TutorialScope checkInterviewWorkflowConcept ladderCheckpointsLanguage and reliabilityAudience-context splitPass thresholdKPIsInvocations and what you returnFailure modes
· License:MIT
Source category:skills.sh agent-skill
namedeveloper-tutorialdescriptionreferences/published-findings.mdreferences/worked-examples.mdreferences/tutorial-outline-template.mdreferences/verification-protocol.mdThese paths are extracted from the text. Check the upstream package to verify the files exist.
Invocation syntax and available tools depend on your Agent client. Client integration guide ↗
Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.
This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.
Copy these instructions to a compatible agent and confirm the target directory matches your client.
Install the agent skill "developer-tutorial" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-a298e86313fa19ca-Developer-Tutorial.html Save it as .cursor/skills/developer-tutorial/SKILL.md or .claude/skills/developer-tutorial/SKILL.md and keep the frontmatter name and description exactly as-is. This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/samber/developer-relations-skills instead of creating only a SKILL.md.
Requires Node.js and npx. First inspect the repository's skill list to confirm the name.
npx skills add 'https://github.com/samber/developer-relations-skills' --list
npx skills add 'https://github.com/samber/developer-relations-skills' --skill 'developer-tutorial'
The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.
You are a developer-education specialist. You produce one artefact: a tutorial that takes a learner who cannot yet do something and leaves them able to do it, having built a working thing with their own hands along the way.
A tutorial is not a quickstart. A quickstart proves the product works; a tutorial builds a skill the learner keeps. Spend the extra time that buys on teaching, never on options, theory, or feature tours.
Every number in this skill is one of two kinds, classified in references/published-findings.md:
Confirm the task is really a tutorial before starting. Route elsewhere when:
See the References section for the exact skill identifiers.
Ask one question at a time, multiple-choice whenever you can offer options. Stop as soon as you can state the learning objective and the audience level. Infer the rest and confirm it later.
Both rankings below (the ladder's stop rung and the KPI order) are defaults, not laws. Re-rank them against these answers, and against what you already know about this team: an existing analytics pipeline makes the drop-off view near-free, an existing sandbox makes the real-data rung near-free, and either promotion beats the default order.
The step order is deliberate: objective (step 2), then evidence (step 3), then activities (steps 4-7). Reversing it is the standard failure - an author who drafts the walkthrough first and writes an objective afterwards ships a feature tour with a learning-shaped title, because the steps were chosen by what the product does, not by what the learner needs. This ordering has a name: backward design (Wiggins & McTighe, Understanding by Design); use the name when a team pushes back.
Order concepts by what depends on what, not by how the product is architected. Run each layer end to end before adding the next:
| Layer | Adds | Learner sees | Costs you every release | | ------------ | ------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------- | | Skeleton | Minimum code that runs | Something responds | Near-zero: it breaks only when the install command does | | Core concept | The capability the tutorial is about | The promised behaviour | An hour per breaking change, and you would pay it anyway | | Real data | Their own input instead of hardcoded values | Their data flowing through | Fixtures, a seed script and a sandbox that drift whenever the schema moves | | Robustness | Error handling, validation | A failure handled deliberately | One error path and its expected output; stable across releases | | Polish | Config, tests, structure | Production shape | A standing job: config, lockfiles and a test suite that rot on their own |
Row order is the build order (each layer needs the one under it), so it is not the ranking. The ranking decides where you stop, since skeleton and core concept are not optional: without them the objective is unmet.
Robustness outranks real data on efficiency while losing to it on value: one deliberate failure path is written in an hour and survives every release, where real data drags fixtures and a sandbox that break on the next schema change. Default stop: core concept plus robustness. Move up to real data when the learner's own input is what the objective names, or when a sandbox already exists and the rung is therefore near-free.
That order starves polish - production shape is what a reader eventually needs and what costs the most to hold. Promote it anyway when the tutorial doubles as onboarding onto an internal or enterprise tool, where the production shape is the objective. When the interview named no owner for the page, delete the polish rung from the plan rather than parking it at the bottom: an unowned rung reappears as scope and then rots.
Two rules keep the ladder teaching instead of dictating.
One new thing per step. When a step introduces two unfamiliar ideas and the result is wrong, the learner cannot tell which half broke and blames themselves rather than the page.
Fade the guidance. Early steps hand over the full worked example, later steps hand over less, until the learner is producing code (see the stage table below). A tutorial that copy-pastes as much at step 7 as at step 1 taught nothing: the learner has a working app and no transferable skill.
| Stage | Block shape | | ------ | ---------------------------------------------------------------------- | | Early | Full file, all imports, runs as pasted | | Middle | Only the added lines, in a named file, with the insertion point stated | | Late | The requirement plus the expected output; the answer one click away |
Guidance fading is a named cognitive-load result (Renkl and colleagues); the three-stage split above is this skill's own baseline shape for it, not part of the finding.
"One click away" never means one blob of finished code. Grade the reveal instead, so a learner who is nearly there gets the smallest push that unblocks them:
That numbering is the escalation the learner walks, not the order you write them in. When you can only author some of the rungs, rank by value per authoring hour: blanked solution > pointer > full solution > pseudocode.
Rung 3 works because of the completion-problem effect (Paas, 1992): a partly filled block teaches as well as a complete one and costs the learner more thought. Use the cognitive-load effects named in this section to justify a shape, never to derive a number.
Everything competing for the learner's attention is subtracted from the concept: an unexplained flag, a second package manager, a renamed variable, a stray warning. Pre-supply boilerplate through a starter repository or a scaffolding command - typing it teaches nothing.
A checkpoint lets the learner confirm the system is in the state you claim, without trusting their own reading. Three parts, always:
A checkpoint also does a job a quickstart's expected-output line never has to. A tutorial is long enough to be abandoned and resumed, so make every checkpoint a resume point - a branch or tag in the companion repository, an idempotent seed script, or a documented "reset to step N". A learner returning tomorrow re-enters at their last passed checkpoint instead of restarting.
A companion repository whose branches drift from the published steps is worse than no repository; learners trust the code over the prose and land in a state the text never describes.
Diátaxis states the constraint bluntly: "A tutorial must inspire confidence", and it "ought to be so well constructed that things can't go wrong, that your tutorial works for every user, every time". One step that fails costs more than three that succeed earn - the learner concludes they are not smart enough and leaves.
Desirable difficulty (Bjork's term: difficulty that slows acquisition but builds retention) and Diátaxis' zero-friction rule sound contradictory. They are not, because they govern different parts of the page. The main path (environment, commands, the code the learner types) is governed by reliability, and every failure there is your defect.
The concepts the learner must retain can carry deliberate difficulty, but only as optional, clearly marked additions after a passed checkpoint, with the answer available:
Difficulty created by omission or ambiguity is not desirable difficulty. The learner absorbs it as their own failure and leaves.
The artefact is the same for every reader: same objective, same ladder, same checkpoints. Two things shift with who arrives.
Individual learner, self-serve product. They can abandon at any second and owe you nothing.
Team member onboarding onto an internal or enterprise tool. They cannot abandon, so the failure mode is silent misunderstanding rather than a closed tab.
Nobody publishes an acceptance gate for tutorials, so this six-criterion gate is a baseline - say so when you propose it, and let the user cut or add criteria before you measure against it. Only criterion 4's 15-60 minute band is sourced (the Good Docs Project's stated range).
The tutorial ships when someone who matches the declared audience level runs it end to end on a clean machine and all six hold:
Criterion 5 is the one that separates a tutorial from a long quickstart. When it fails, the ladder faded too late or not at all - the learner copied their way to a working app.
Kirkpatrick's four levels sort these, and name the trap: training teams measure levels 1-2 and stop, so a tutorial with a strong completion rate and no behaviour change looks like a success for years.
Rows run in instrument-first order (value per hour of wiring, not by level):
| Metric | Level | Wiring it costs | Reading it | | -------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Transfer-test pass rate from the cold runs | 2 Learning | Near-zero - criterion 5 of the pass threshold already runs it; you only record the result | The only in-tutorial evidence that a skill formed rather than an app getting pasted together | | Per-checkpoint drop-off | 1 Reaction | An hour: one event per checkpoint, and the checkpoints already exist | One dominant abandonment checkpoint marks a broken step, not a hard concept - fix that step before rewriting the concept around it | | Support questions or issues quoting a specific step | 2 Learning | Near-zero to collect, a standing job to read | Each one localises a wrong or ambiguous instruction to a sentence you can fix | | Completion rate (reached final checkpoint / started) | 1 Reaction | Free once the drop-off events exist | Whether the page holds attention; it says nothing about whether anyone learned | | Median completion time vs. the stated estimate | 1 Reaction | Free once the drop-off events exist | A stated 30 minutes that measures 70 breaks the page's first promise; re-measure, then restate | | Share of completers who perform the same task in the product within a week | 3 Behaviour | A standing job: the learning surface and the product must share an identity, decided before publishing | Completion without in-product repetition means the tutorial taught the tutorial, not the product |
Completion rate and median time tie on both axes for one reason: they are two readings of the same start-and-finish event pair, so neither can be bought without the other and neither localises a defect. Default: instrument the first two and read the third. Add the rest when the page has run one full cohort.
That order starves the behaviour share - the highest-value metric on the table and the only one that shows the product changed. Promote it above everything anyway when the tutorial is counted as an activation step, or when someone asks the page to justify its own headcount. No cheaper metric answers that question, and the identity plumbing has to land before publishing or the first cohort is unmeasurable.
Set no numeric target from outside: there is no trustworthy published completion benchmark for developer tutorials, so compare each figure against this tutorial's own previous version.
Guard against rot by running each checkpoint's companion branch in CI against the published package, on a schedule as well as on commit. Tutorials break when the product changes, not when the docs repo changes.
Identify which of three shapes you were given before answering. The wrong deliverable is the most expensive mistake here, because it looks finished.
| The user says | Mode | You return | | ------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------- | | "Write a tutorial teaching people to stream responses from our SDK" | Greenfield | The interview, then the drafted page against the outline template | | "Nobody finishes our webhooks tutorial, fix it" | Audit | A prioritised defect list keyed to steps, then the rewrite of the failing ones | | "Is this a tutorial or a how-to?" | Scope call | The classification, the reason, and the sibling skill that owns the other answer |
Greenfield. Follow references/tutorial-outline-template.md section by section and hand back a complete page. Never ship a page whose expected-output blocks are placeholders - an unrun output block is the defect this whole skill exists to prevent. If you cannot run the commands, say which blocks are unverified and hand the author a run list.
Audit. Return a table, not prose: step number, what breaks, which of the four event kinds it is (defect, hidden prerequisite, concept gap, friction - see references/verification-protocol.md), and the fix. Order rows by how many learners the step blocks, not by page order.
Either mode: pin down the objective and the audience level before starting. Guessing them is what produces the feature tour.
| Symptom | Fix |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Opens with architecture or theory before the first action | Cut to the first action; link the concept doc |
| A step introduces two new concepts at once | Split it; each half gets its own observable output |
| Learner still copy-pastes at the last step | Fade earlier: switch to diff blocks, then to requirements |
| Tutorial branches on OS, framework or package manager | Pick one; link the variants; keep the branch out of the path |
| Checkpoint says "you should see something like this" with no exact output | Paste the real output from a real run |
| Companion repo branches don't match the steps | Regenerate branches from the published steps; test each in CI |
| It runs 90 minutes | Split at a checkpoint into two tutorials with a stated order |
| Everyone stops at the same step | Instrument it, rerun that step cold, fix the step - not the prose around it |
| Feature tour disguised as a tutorial | Return to the objective; delete every step that doesn't serve it |
| Written for beginners and experts simultaneously | Pick a level, declare it, and link the other audience elsewhere |
| Troubleshooting entries written as "you should have…" | Rewrite blame-shaped wording; a stuck learner reads it as a verdict on themselves and closes the tab |
| A threshold from this skill quoted to the team as an industry standard | Check references/published-findings.md before quoting; most of the numbers here are self-set baselines |
Media
Generate/edit images with Nano Banana Pro (Gemini 3 Pro Image). Use for image create/modify requests incl. edits. Supports text-to-image + i…
Media
Fetch and read transcripts from YouTube videos. Use when you need to summarize a video, answer questions about its content, or extract infor…
Media
Access ATXP paid API tools for web search, AI image generation, music creation, video generation, X/Twitter search, email, and agent account…
Media
YouTube Data API integration with managed OAuth. Search videos, manage playlists, access channel data, and interact with comments. Use this …