name: documentation-tutorial description: Build hands-on, code-first tutorials from any primary source - technical documentation, codebases, APIs, tools, or other complex material. Extract real examples, working code, and concrete scenarios. Create tutorials using markdown (text-heavy summaries) or React artifacts (complex interactive workflows). Keywords - tutorial, codebase, API, hands-on, code-first, copy-paste, interactive, real examples, primary source

Tutorial Developer from Primary Sources

Transform any primary source into hands-on, practical tutorials that prioritize real, working examples over conceptual explanations. Focus on what users need to do, not what they need to understand.

Quick Decision Guide

Step 1: Choose format

Text-heavy summary or CLI reference → Markdown
Complex workflow with multiple steps → React Artifact

Step 2: Follow the three pillars

Real code/commands (not pseudocode)
Real use cases (concrete scenarios)
Mental model (one-sentence explanation)

Core Principles

The Three Pillars

Every tutorial must clearly answer:

Real Code: What's the actual code or command I run? (Copy-paste executable, no pseudocode)
Real Use Cases: When would I actually use this? (Concrete scenarios like "healthcare bot", not vague descriptions)
Mental Model: How does this work? (One-sentence explanation enabling independent problem-solving)

Example:

Mental Model: "AI generates interactive React components from natural language prompts, streaming in real-time."

Code:
curl -X POST https://api.thesys.dev/v1/ui/generate \
  -H "Authorization: Bearer sk-thesys-key" \
  -d '{"prompt": "Create a booking form", "model": "gpt-4"}'

Use Case: When you want users to book appointments without writing React,
send a prompt and stream the form directly into the page.

Code-First Approach

Lead with working examples, not theory
Real endpoints (actual URLs, not <placeholder>)
Exact payloads (complete JSON, not simplified)
No high-level summaries unless essential
Get users to running code within 5 minutes

Systematic Workflow

Phase 1: Extract from Primary Source

Step 1: Identify Core Mental Model

Answer: "What's the one-sentence explanation that makes everything click?"

Examples:

API: "AI generates interactive UIs from prompts, streaming real-time"
Tool: "PDFs are structured data; extract tables/text like CSV/JSON"
Codebase: "Request flows through middleware → router → handler → response"
Academic Paper: "YouTube Data API v3 lets you search videos, get metadata, and filter by captions/views/category using REST endpoints"

Primary Source Types

Documentation: Official API docs, SDK references, CLI manuals

Codebases: Open source projects, example repos

Tools: Software applications, command-line utilities

Academic Papers: Research methodologies in appendices/supplementary materials

Look for: Data collection procedures, API workflows, filtering criteria, implementation details
Example: MINEDOJO paper Appendix D.1 documents exact YouTube API usage with 5-step workflow
Extract: Step-by-step procedures, quota limits, legal considerations, real filtering parameters
Value: More rigorous methodology than typical blog posts, validated by peer review

Step 2: Find Real Examples

Extract from docs/code:

Working code (not pseudocode)
CLI commands with actual flags
API calls (curl + request/response)
Config files, error cases

Step 3: Extract Concrete Use Cases

❌ Wrong: "Can be used for various applications like analytics, reporting, etc."

✅ Right:

Analytics Dashboard: User asks "show me sales by region" → AI generates chart
Booking Flow: Customer books appointment → form auto-generates with calendar
Support Tickets: Agent asks "show ticket queue" → interactive table generates

For each: What triggers it, what code is needed, what user sees, why it matters.

Phase 2: Structure Tutorial

Step 4: Plan Sections (Action-oriented names)

Section 1: "⚙️ Setup & Install" → Running in 5 minutes
Section 2: "🚀 First API Call" → Verify it works
Section 3: "🌐 Core Operations" → Major endpoints
Section 4: "🐍 SDK Examples" → Language-specific code
Section 5: "💾 Real Scenario" → Complete workflow

Step 5: Plan Code Blocks

Copy-paste executable curl with real endpoint
Tabs: cURL → Request Body → Response
Real data values (names, dates, actual fields)
Error cases if documented

Step 6: Plan Workflow

Choose actual use case from documentation
Break into 3-5 sequential API calls
Show how responses flow into next step

Phase 3: Implement

Step 7: For React Artifacts

Structure:

Sidebar navigation (6-8 focused sections)
Main content area with code blocks
Copy buttons on all code
Tabbed views (curl/request/response)

Step 8: Code Block Spec

Dark background, language label, copy button
Left-aligned monospace, syntax highlighting
No line numbers (confuses copy-paste)

Step 9: Quality Check (see checklist at end)

Tutorial Patterns

Pattern: API Endpoints

TITLE: Endpoint Name (POST /v1/endpoint)
DESCRIPTION: One sentence
CODE BLOCK: Tabs (cURL | Request | Response)
USE CASE: One sentence + real scenario

Pattern: Complete Workflows

STEP 1: First API Call
  Context (1 sentence) → Code → Result
STEP 2: Second API Call
  Context (how previous flows here) → Code → Result
STEP 3: Final Outcome

Pattern: Setup/Installation

PREREQUISITES: What they need
COMMAND: Full copy-paste command
VERIFY: One-line check
TROUBLESHOOTING: Common issues

Pattern: SDK Examples

LANGUAGE: Python/JavaScript/etc
CODE: Full working function (imports, async/await, error handling)
RUN IT: How to execute
OUTPUT: Expected result

6-8 focused sections (not monolithic)
Emoji + action verbs: "⚙️ Setup", "🚀 First Call"
Reduces cognitive load, improves completion

Pattern: Copy Buttons

One-click copy-to-clipboard (right corner)
Visual feedback when copied (checkmark, 2 seconds)
3x higher code execution rate

Pattern: Mental Models First

Present one-sentence model after first working example
Place in colored box: "💡 How This Works"
Enables independent problem-solving

Pattern: Progressive Disclosure

Section 1: Minimum to get running
Section 2: Simplest successful request
Section 3-4: Core operations, multiple languages
Section 5: Complete multi-step workflow
Section 6: Advanced features
Section 7: Troubleshooting

Pattern: Concrete Use Cases

## Common Use Cases

1. **Analytics Dashboard** (5 min read)
   You want users to ask "show me Q3 revenue"
   → AI generates interactive chart

2. **Booking Form** (7 min read)
   You need booking flow without React
   → AI generates form with calendar

[Pick your use case →]

Benefit: Users self-select relevant tutorial path.

Pattern: Troubleshooting

Color-coded sections (red=critical, yellow=common)
For each: Problem → Root cause → Solution → Code
Include CORS, auth failures, timeouts

Quality Checklist

Three Pillars:

Real code (copy-paste executable: curl, Python, JavaScript)
Real use cases (3-5 concrete scenarios, not "theoretical")
Mental model (one-sentence explanation)

Code Quality:

Real endpoints (no <placeholder>)
Real data (Sarah Chen, 2025-11-15, actual field names)
Tabs: cURL + Request + Response
Left-aligned, properly formatted

Structure:

First section: Running code in <5 minutes
6-8 focused sections with navigation
Complete workflow (form → submit → confirm)
Multiple languages (Python, JavaScript, HTTP)

Content:

Mental model within first 2 examples
No conceptual fluff or "learning objectives"
Real-world scenario shows data flowing
Troubleshooting with real problems

Interactive (for React artifacts):

Copy buttons on all code
Users can complete real task after tutorial

Real Examples

Example 1: Mail Command (Markdown)

Why Markdown: CLI reference with many commands

Structure: Basic Sending → Advanced Options → Interactive Mode → Reading Mail → Configuration → Gmail Integration → Quick Reference

Key Features: Copy-paste commands, real config files, organized by workflow

Example 2: Thesys C1 API (React Artifact)

Why React: Complex API needing interactive tabs/navigation

Structure: Setup (5min) → First Call → Core Operations → SDK Examples → Real Scenario → Advanced → Troubleshooting

Key Features: Sidebar navigation, copy buttons, tabbed views, real data, workflow chaining

Academic Study Guides: Quote Integration

Same principle applies to academic primary sources (historical documents, philosophical texts, legal cases): transform into practical guide.

Core Principle

Embed quotes throughout analysis where they support arguments. NOT collected at end.

Pattern

Question → Quote → Interpretation → Quote → Synthesis

NOT: Question → Summary → All Quotes at End

Example

## Was Qianlong's Response Wise?

Qianlong defended sovereignty. He explained:

> "If other nations imitate your evil example... how could I possibly comply?"

His reasoning was sound: granting Britain privileges would force him to grant all nations the same.

However, his rejection showed complacency:

> "Strange and costly objects do not interest me."

By dismissing British technology, he missed intelligence-gathering opportunities.

Debate Format

Clear position
8-10 numbered arguments (each with quote evidence)
Rebuttals section
Conclusion

Each argument: Claim → Quote → Interpret → Connect to thesis

Checklist

Quotes embedded at point of analysis
Every claim supported by quote
Each quote followed by interpretation
Creates "guide through sources"

File Organization

CRITICAL: All tutorials follow this organization pattern:

1. Markdown Tutorials → claude_files/tutorial/

# Create in project's claude_files/tutorial directory
mkdir -p claude_files/tutorial

# Create tutorial file there
# Example: claude_files/tutorial/youtube-data-api.md

Naming convention:

Lowercase, kebab-case
Descriptive: {technology}-{purpose}.md
Examples: youtube-data-api.md, python-cli-tutorial.md, docker-compose-guide.md

2. HTML Tutorials → claude_files/html/

# Create in project's claude_files/html directory
mkdir -p claude_files/html

# Create HTML file there
# Example: claude_files/html/youtube-data-tutorial.html

Naming convention:

Lowercase, kebab-case
Descriptive: {technology}-{purpose}.html
Examples: youtube-data-tutorial.html, api-comparison.html

3. Why This Pattern?

Project-specific - Tutorials live with the code they document
Version controlled - Part of the project, tracked in git
Self-contained - Everything in claude_files/ for easy cleanup
Consistent location - Always claude_files/tutorial/ or claude_files/html/
No symlinks - Direct files, no complicated linking

Workflow

When creating a tutorial:

Markdown:

Run: mkdir -p claude_files/tutorial
Create: claude_files/tutorial/{name}.md
Preview: nvim -c "MarkdownPreview" claude_files/tutorial/{name}.md

HTML:

Run: mkdir -p claude_files/html
Create: claude_files/html/{name}.html
Open: open claude_files/html/{name}.html

Tools & Preview

Build: building-artifacts skill (React + Tailwind + shadcn/ui) Format: Dark code blocks with copy buttons, monospace Layout: Sidebar + main content

Preview markdown tutorials:

CRITICAL: Always open markdown tutorials with preview immediately after creation.

nvim -c "MarkdownPreview" /path/to/tutorial.md

This provides instant visual feedback and allows the user to review formatting, code blocks, and overall structure in the rendered view.

Use direct commands (no aliases) for reproducibility.

documentation-tutorial

SKILL.md