From beagle-docs
Provides Diataxis framework patterns and templates for writing tutorial documentation that teaches beginners through guided, hands-on practice.
npx claudepluginhub existential-birds/beagle --plugin beagle-docsThis skill uses the workspace's default tool permissions.
This skill provides patterns for writing effective tutorials following the Diataxis framework. Tutorials are learning-oriented content where the reader learns by doing under the guidance of a teacher.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
This skill provides patterns for writing effective tutorials following the Diataxis framework. Tutorials are learning-oriented content where the reader learns by doing under the guidance of a teacher.
Target readers:
Tutorials are NOT:
Tutorials teach through action, not explanation. The reader should be doing something at every moment.
| Avoid | Prefer |
|---|---|
| "REST APIs use HTTP methods to..." | "Run this command to make your first API call:" |
| "Authentication is important because..." | "Add your API key to authenticate:" |
| "The dashboard contains several sections..." | "Click Create Project in the dashboard." |
After each action, tell readers exactly what they should see. This confirms success and builds confidence.
Run the development server:
```bash
npm run dev
You should see:
> Local: http://localhost:3000
> Ready in 500ms
Open http://localhost:3000 in your browser. You should see a welcome page with "Hello, World!" displayed.
### 3. One Clear Path, Minimize Choices
Tutorials should not offer alternatives. Pick one way and guide the reader through it completely.
| Avoid | Prefer |
|-------|--------|
| "You can use npm, yarn, or pnpm..." | "Install the dependencies:" |
| "There are several ways to configure..." | "Create a config file:" |
| "Optionally, you might want to..." | [Omit optional steps entirely] |
### 4. The Teacher Takes Responsibility
If the reader fails, the tutorial failed. Anticipate problems and prevent them. Never blame the reader.
```markdown
<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>
Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.
Use this structure for all tutorials:
---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---
# Build Your First [Thing]
In this tutorial, you'll build a [concrete deliverable]. By the end, you'll have a working [thing] that [does something visible].
<Note>
This tutorial takes approximately [X] minutes to complete.
</Note>
## What you'll build
[Screenshot or diagram of the end result]
A [brief description of the concrete deliverable] that:
- [Visible capability 1]
- [Visible capability 2]
- [Visible capability 3]
## Prerequisites
Before starting, make sure you have:
- [Minimal requirement 1 - link to install guide if needed]
- [Minimal requirement 2]
<Tip>
New to [prerequisite]? [Link to external resource] has a quick setup guide.
</Tip>
## Step 1: [Set up your project]
[First action - always start with something that produces visible output]
```bash
[command]
You should see:
[expected output]
[Brief confirmation of what this means]
[Next action with clear instruction]
[code to add or modify]
Save the file. You should see [visible change].
[Optional tip to prevent common mistakes][Continue with more steps, each producing visible output]
[Bring it together with a final step]
You should now see [final visible result].
[Screenshot of completed project]
In this tutorial, you:
Now that you have a working [thing], you can:
## Writing Principles
### Title Conventions
- **Start with action outcomes**: "Build your first...", "Create a...", "Deploy your..."
- Focus on what they'll make, not what they'll learn
- Be concrete: "Build a chat application" not "Learn about real-time messaging"
### Step Structure
1. **Lead with the action** - don't explain before doing
2. **Show exactly what to type or click** - no ambiguity
3. **Confirm success after every step** - "You should see..."
4. **Keep steps small** - one visible change per step
### Managing Prerequisites
Tutorials are for beginners, so minimize prerequisites:
```markdown
## Prerequisites
- A computer with macOS, Windows, or Linux
- A text editor (we recommend VS Code)
- 15 minutes of time
<Tip>
You don't need any programming experience. This tutorial explains everything as we go.
</Tip>
This is the most important pattern in tutorial writing. Use it constantly:
Click **Save**. You should see a green checkmark appear next to the filename.
Run the test:
```bash
npm test
You should see:
PASS src/app.test.js
✓ renders welcome message (23ms)
Tests: 1 passed, 1 total
### Handling Errors Gracefully
Anticipate failures and guide readers back on track:
```markdown
<Warning>
If you see "Module not found", make sure you saved the file from Step 2.
Return to Step 2 and verify the import statement matches exactly.
</Warning>
Show what success looks like:
<Frame caption="Your completed dashboard should look like this">
</Frame>
For numbered sequences within a step:
<Steps>
<Step title="Open the settings panel">
Click the gear icon in the top right corner.
</Step>
<Step title="Find the API section">
Scroll down to **Developer Settings**.
</Step>
<Step title="Generate a key">
Click **Create New Key** and copy the value shown.
</Step>
</Steps>
<Note>
Don't worry if the colors look different on your screen.
We'll customize the theme in the next step.
</Note>
<Warning>
Make sure to save the file before continuing.
The next step won't work without this change.
</Warning>
<Tip>
You can press Cmd+S (Mac) or Ctrl+S (Windows) to save quickly.
</Tip>
Draw attention to what matters:
```javascript {3-4}
function App() {
return (
<h1>Hello, World!</h1>
<p>Welcome to your first app.</p>
);
}
## Example Tutorial
See [references/example-weather-api.md](references/example-weather-api.md) for a complete example tutorial demonstrating all principles above. The example builds a weather dashboard that fetches real API data.
## Checklist for Tutorials
Before publishing, verify:
- [ ] Title describes what they'll build, not what they'll learn
- [ ] Introduction shows the concrete end result
- [ ] Prerequisites are minimal (beginners don't have much)
- [ ] Every step produces visible output
- [ ] "You should see" appears after each significant action
- [ ] No choices offered - one clear path only
- [ ] No explanations of why things work (save for docs)
- [ ] Potential failures are anticipated with recovery guidance
- [ ] "What you've learned" summarizes concrete skills gained
- [ ] Next steps guide to continued learning
- [ ] Tutorial tested end-to-end by someone unfamiliar with it
## When to Use Tutorial vs Other Doc Types
| User's mindset | Doc type | Example |
|---------------|----------|---------|
| "I want to learn" | **Tutorial** | "Build your first chatbot" |
| "I want to do X" | How-To | "How to configure SSO" |
| "I want to understand" | Explanation | "How our caching works" |
| "I need to look up Y" | Reference | "API endpoint reference" |
### Tutorial vs How-To: Key Differences
| Aspect | Tutorial | How-To |
|--------|----------|--------|
| **Purpose** | Learning through doing | Accomplishing a specific task |
| **Audience** | Complete beginners | Users with some experience |
| **Structure** | Linear journey with one path | Steps to achieve a goal |
| **Choices** | None - one prescribed way | May show alternatives |
| **Explanations** | Minimal - action over theory | Minimal - focus on steps |
| **Success** | Reader learns and gains confidence | Reader completes their task |
| **Length** | Longer, more hand-holding | Shorter, more direct |
## Related Skills
- **docs-style**: Core writing conventions and components
- **howto-docs**: How-To guide patterns for task-oriented content
- **reference-docs**: Reference documentation patterns
- **explanation-docs**: Conceptual documentation patterns