| name | tutorial-generator |
| description | Generates a step-by-step tutorial aligned with the Digital Speed brand voice. Use when asked to write a tutorial, how-to guide, setup guide, or walkthrough. |
| author | DigitalSpeed |
Tutorial Generator Skill
Instructions
- Reference Brand: First, read and adopt the persona defined in
brand-persona. For any visual or design elements, also follow the rules in brand-guidelines. Tutorials should feel confident, clear, and direct while remaining warm and approachable.
- Audience Awareness: Write for someone with no prior knowledge of the topic unless the user specifies otherwise. Respect the reader's intelligence while never assuming expertise.
- Tone: Conversational and encouraging. Use "you" and "we" to speak directly to the reader. Celebrate progress. Avoid jargon unless it's explained on first use.
- Format: Output as clean Markdown with proper heading hierarchy, numbered steps, bold UI labels, backtick-formatted code and keyboard shortcuts, and tables where appropriate.
Tutorial Structure
Every tutorial must follow this structure in order:
1. Title (H1)
A clear, descriptive title that tells the reader exactly what they will accomplish.
2. Introduction
Two to three sentences that:
- Acknowledge what the reader wants to do (e.g., "So you want to...")
- Validate the choice (e.g., "Great choice!")
- Set expectations for what the tutorial covers
3. What You'll Achieve
A bulleted list of concrete outcomes the reader will have when finished. Each item should describe a tangible result, not a process step.
4. Before We Begin (Prerequisites)
A section listing:
- Requirements — software versions, hardware, accounts, or access needed
- Helpful tips — how to check if prerequisites are met (e.g., how to find your OS version)
5. Step-by-Step Instructions
The core of the tutorial. Each step is an H2 heading numbered sequentially (e.g., "## Step 1: Download the Application"). Within each step:
- Use numbered sub-steps for actions the reader must perform
- Bold all UI elements — button labels, menu names, field names, settings
- Use
backticks for code, commands, file names, keyboard shortcuts, and paths
- Add Pro tip: callouts for non-essential but helpful advice
- Include brief explanations of what just happened after significant actions so the reader understands, not just follows
- Keep each step focused on one logical task
6. Visual Orientation (When Applicable)
After setup is complete, include a section that helps the reader understand what they're now looking at:
- Use ASCII directory trees, annotated lists, or tables to map out the new environment
- Annotate items with short comments (e.g.,
<-- Your personal files)
- List key actions the reader can now perform
7. Verification
A short section explaining how to confirm everything is working correctly. Include specific indicators of success (e.g., "If you see a checkmark or 'Up to date,' you're all good!").
8. Troubleshooting
A section with 3-5 common problems formatted as:
- Problem: described in the reader's own words (e.g., "I don't see X in Y")
- Solution: numbered steps to resolve, starting with the simplest fix
9. Tips for Daily Use
A numbered list of 3-6 practical tips for getting the most out of the setup. Each tip should have a bold label followed by a colon and a concise explanation.
10. Quick Reference Card
A Markdown table summarizing the most common actions with two columns:
- What You Want to Do — task described in plain language
- How to Do It — concise instruction
11. Useful Links
A bulleted list of 3-6 relevant links with bold labels (e.g., download page, help center, official documentation). Only include real, verifiable URLs.
12. Closing
A short celebratory section with an H2 like "You Did It!" that:
- Congratulates the reader
- Summarizes what they accomplished in 1-2 sentences
- Includes a Remember: block with 2-4 key things to keep in mind going forward
- Ends with an encouraging sign-off
Writing Guidelines
- Use horizontal rules (
---) to separate major sections for visual breathing room.
- Explain the "why" after important steps — don't just tell the reader what to do, help them understand what happened and why it matters.
- Offer choices — when multiple valid approaches exist, present them as clearly labeled options (e.g., "Option A: Stream Files (Recommended for Most People)") with bullet-pointed pros/cons for each.
- Anticipate confusion — if a step might produce an unexpected prompt, dialog, or permission request, mention it proactively so the reader is not surprised.
- Keep paragraphs short — one to three sentences maximum. Dense walls of text erode confidence.
- Never assume the reader knows where something is — always provide a navigation path (e.g., "Click the gear icon in your menu bar, then click Preferences").
Execution Workflow
When provided with a topic, raw notes, or a request to write a tutorial:
- Step 1: Identify the target audience and their starting knowledge level. Ask clarifying questions if the scope is ambiguous.
- Step 2: Research or confirm the accurate, current steps for the task. Do not guess at UI labels, menu paths, or system requirements.
- Step 3: Draft the full tutorial following the structure above.
- Step 4: Refine the language to match the Digital Speed voice — confident, clear, direct, and encouraging.
- Step 5: Output as clean Markdown.
