Skip to main content
skill CX Codex

tutorial-design — Claude Code skill: what it does, how to install

tutorial-design guides you through writing hands-on tutorials, workshops, and coding guides with explicit checkpoints and troubleshooting sections.

MIT 102 installs ★ 71 updated 2026-06-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NickCrew/Claude-Cortex --skill tutorial-design -a claude-code
Open on GitHub

What tutorial-design does

The skill organizes tutorial writing into a structured five-phase cycle: defining measurable outcomes, decomposing concepts into sequenced steps, designing exercises, drafting code, and validating paths. It outlines multiple task formats, covering syntax fill-ins, code refactoring, and debugging challenges.

Each section follows an exact structure containing a runnable snippet, line-by-line explanation, a verification instruction, and error resolutions. The skill explicitly depends on Read and Write tools alongside peer skills documentation-production and code-explanation.

Without testing common runtime errors beforehand, the mandatory troubleshooting sections cannot be filled accurately.

What it helps with

  • write step-by-step getting started guides for APIs and libraries
  • structure technical workshop materials with clear outcomes
  • add self-assessment checkpoints and debugging tasks to docs
  • break complex technical topics into progressive learning steps

Example prompts for the agent

  • Write a hands-on tutorial for building an HTTP service with checkpoints and troubleshooting
  • Design a 45-minute workshop session with debugging challenges
  • Create a 5-minute quick start guide for our command-line tool

How to install tutorial-design

1Skills CLI (Vercel)

npx skills add NickCrew/Claude-Cortex --skill tutorial-design -a claude-code

2Manually: put the files in place

~/.claude/skills/tutorial-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tutorial-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tutorial-design

How to install tutorial-design in Claude Code?

Run npx skills add NickCrew/Claude-Cortex --skill tutorial-design -a claude-code. The skill file will be placed in ~/.claude/skills/tutorial-design/SKILL.md.

What does tutorial-design do?

It enforces a phased tutorial methodology that incorporates runnable snippets, progress checkpoints, and common error diagnostics.

What dependencies does this skill require?

It lists dependencies on the documentation-production and code-explanation skills, plus access to Read and Write tools.

Source text

SKILL.md · MIT
---
name: tutorial-design
description: Design and write hands-on tutorials with progressive disclosure, exercises, and troubleshooting sections. Use when creating learning content, workshops, or step-by-step guides.
version: 1.0.0
tags:
  - tutorials
  - pedagogy
  - learning
  - workshops
  - documentation
triggers:
  - write tutorial
  - create workshop
  - step-by-step guide
  - hands-on walkthrough
  - learning content
  - lab exercise
dependencies:
  skills:
    - documentation-production
    - code-explanation
  tools:
    - Read
    - Write
token_estimate: ~2500
keywords:
  - write tutorial
  - learning content
  - hands-on guide
  - tutorial
  - tutorial design
---

# Tutorial Design

Design and write hands-on tutorials that transform complex technical concepts into engaging,
progressive learning experiences with exercises, checkpoints, and troubleshooting guidance.

## When to Use This Skill

- Writing a getting-started tutorial for a library, API, or tool
- Creating workshop materials for team training or conferences
- Building multi-part learning series with progressive difficulty
- Designing coding exercises with self-assessment checkpoints
- Converting existing documentation into guided learning content
- Creating quick-start guides that get users productive fast

## Quick Reference

| Resource | Purpose | Load when |
|----------|---------|-----------|
| `references/design-patterns.md` | Progressive disclosure patterns, exercise types, checkpoint design, difficulty calibration, prerequisite mapping | Planning tutorial structure or designing exercises |

---

## Workflow Overview

```
Phase 1: Objectives   → Define learning outcomes, prerequisites, and audience
Phase 2: Decompose    → Break concepts into atomic, sequenced steps
Phase 3: Design       → Create exercises, checkpoints, and troubleshooting tips
Phase 4: Write        → Produce tutorial content with runnable examples
Phase 5: Validate     → Test the tutorial path end-to-end
```

---

## Phase 1: Define Learning Objectives

Every tutorial starts with clear outcomes.

### Opening Section Template

```markdown
## What You'll Learn

- [Specific, measurable outcome 1]
- [Specific, measurable outcome 2]
- [Specific, measurable outcome 3]

## Prerequisites

- [Required knowledge or setup]
- [Tools needed]

## Time Estimate

~[X] minutes

## What You'll Build

[Brief description or screenshot of the final result]
```

**Writing good objectives:**
- Use action verbs: "build", "configure", "debug", "deploy" — not "understand" or "learn about"
- Make them testable: the reader should be able to verify they achieved each outcome
- Scope realistically: 3-5 objectives per tutorial

---

## Phase 2: Concept Decomposition

Break the topic into atomic learning steps.

### Sequencing Rules

1. **One concept per section** — never introduce two new ideas at once
2. **Dependency order** — concepts must build on what came before
3. **Concrete before abstract** — show the working example, then explain the theory
4. **Simple before complex** — start with the minimal version, layer complexity

### Concept Map

Before writing, sketch a dependency graph:

```
[Prerequisites] → [Core concept A] → [Core concept B]
                                    ↘ [Variation 1]
                  [Core concept A] → [Core concept C] → [Advanced topic]
```

Each node becomes a section. Dependencies become the section order.

---

## Phase 3: Design Exercises and Checkpoints

### Exercise Types

| Type | Difficulty | When to use |
|------|-----------|-------------|
| **Fill-in-the-blank** | Low | Reinforce syntax after an example |
| **Debug challenge** | Medium | Teach error reading and common mistakes |
| **Extension task** | Medium | Add a feature to working code |
| **From scratch** | High | Build based on requirements only |
| **Refactoring** | High | Improve existing implementation |

### Checkpoint Pattern

After every major section, insert a checkpoint:

```markdown
### Checkpoint

At this point you should have:
- [ ] A running server on port 3000
- [ ] The `/health` endpoint returning `{ "status": "ok" }`
- [ ] Server logs showing incoming requests

**If something's wrong**, see the [Troubleshooting](#troubleshooting) section below.
```

### Troubleshooting Sections

For every section, anticipate 2-3 common errors:

```markdown
### Troubleshooting

**Error: `EADDRINUSE: address already in use`**
Another process is using port 3000. Run `lsof -i :3000` to find it,
then stop it or change your port.

**Error: `Cannot find module 'express'`**
You haven't installed dependencies yet. Run `npm install` in the project root.
```

---

## Phase 4: Write the Tutorial

### Section Structure (for each concept)

1. **Brief intro** (1-2 sentences) — what this section covers and why it matters
2. **Minimal example** — complete, runnable code showing the concept
3. **Line-by-line explanation** — walk through the important parts
4. **Try it** — tell the reader to run the code and what to expect
5. **Extend it** — optional exercise to deepen understanding
6. **Troubleshooting** — common errors for this section

### Writing Principles

- **Show, then explain** — code first, theory second
- **Frequent validation** — readers should run code every 2-3 minutes
- **Fail forward** — include intentional errors to teach debugging
- **Incremental complexity** — each step adds one thing to the previous
- **Copy-paste friendly** — examples must work when pasted directly

### Content Elements

**Code blocks must:**
- Be complete and runnable (no `...` elisions in critical paths)
- Include expected output in a separate block
- Use meaningful variable names
- Have inline comments only where non-obvious

**Explanations should:**
- Connect to real-world use cases
- Provide the "why" behind each step
- Use analogies to familiar concepts
- Anticipate the reader's "but what about...?" questions

### Closing Section

```markdown
## Summary

You've learned how to:
- [Outcome 1 restated]
- [Outcome 2 restated]

## Next Steps

- [Natural follow-on tutorial or topic]
- [Related documentation]
- [Community resources]
```

---

## Phase 5: Validate

Before publishing, test the entire tutorial path:

1. Follow every step from a clean environment
2. Run every code example and verify output matches
3. Trigger every troubleshooting scenario at least once
4. Time the tutorial — does it match the estimate?
5. Have someone unfamiliar with the topic attempt it

---

## Tutorial Formats

| Format | Duration | When to use |
|--------|----------|-------------|
| **Quick Start** | 5 min | First contact, get running fast |
| **Deep Dive** | 30-60 min | Comprehensive single-topic exploration |
| **Workshop Series** | Multi-part | Progressive learning across sessions |
| **Cookbook** | Variable | Problem-solution pairs, non-linear reading |
| **Interactive Lab** | 15-45 min | Hands-on environment with guided steps |

## Anti-Patterns

- Introducing concepts before they are needed ("you'll use this later")
- Showing code snippets that cannot run standalone
- Assuming knowledge not listed in prerequisites
- Walls of text without code breaks
- Exercises without solutions (even collapsed/hidden ones)
- Skipping the "why" and only showing the "how"

© NickCrew · MIT · NickCrew/Claude-Cortex

Similar skills

All skills for Writing and docs →

From the same set21

The whole set →
event-driven-architecture The event-driven-architecture skill guides event-driven system design with event sourcing, CQRS, sagas, and message brokers. Use it for microservices and distributed transactions. CX Codex +1 118installs dashboard-designer The dashboard-designer Claude Code skill plans dashboard KPIs, layout, and visual hierarchy. It activates for requests about monitoring dashboards or choosing a BI tool. CX Codex +1 109installs terraform-best-practices terraform-best-practices adds enterprise Terraform guidelines covering module layout, secure remote state, workspace isolation, and CI/CD security scanning. CX Codex +1 109installs mermaid-diagramming mermaid-diagramming gets the agent to write Mermaid diagrams for docs: flowcharts, sequence and ER diagrams, state machines, Gantt charts and architecture views. CX Codex +1 105installs kubernetes-security-policies kubernetes-security-policies — a coding-agent skill that walks through Kubernetes hardening: pod security standards, network policies, RBAC. Useful when a cluster needs tightening before production. CX Codex +1 104installs user-journey-mapping The user-journey-mapping Claude Code skill lays out user journeys with stages, touchpoints, emotions, and friction points. It activates for experience mapping or conversion-flow analysis. CX Codex +1 102installs requirements-discovery The requirements-discovery Claude Code skill gathers requirements, sets project boundaries, and structures PRDs. It activates for feature discovery, stakeholder interviews, or specification reviews. CX Codex +1 101installs api-gateway-patterns api-gateway-patterns — a skill for API gateway design in microservices: routing, authentication, rate limiting, and request composition. CX Codex +1 101installs

Project sponsors

Companies that keep this analytics open