К основному содержанию
скилл CX Codex

tutorial-docs — скилл для Claude Code: что делает и как установить

Скилл tutorial-docs для Claude Code задаёт структуру обучающих руководств по методологии Diataxis. Агент подключает его при написании вводных уроков и пошаговых руководств для новичков.

Apache-2.0 273 установок ★ 89 обновлён 2026-09-15

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add existential-birds/beagle --skill tutorial-docs -a claude-code
Открыть на GitHub

Что делает tutorial-docs

Скилл форматирует обучающие материалы по принципу практического действия: читатель сразу пишет код и проверяет вывод. Каждое действие сопровождается ожидаемым результатом через паттерн «You should see». В тексте исключаются развилки и альтернативные варианты настройки, чтобы новичок не запутался в инструментах.

В шаблон заложен тон от первого лица множественного числа («мы создадим», «давайте проверим»). Возможные ошибки читателя скилл предписывает предупреждать заранее блоками <Warning>, не перекладывая вину за сбой на пользователя.

Для полноценной работы скилл опирается на базовые правила из docs-style. Параметр user-invocable: false означает, что агент активирует эти правила автоматически при запросе на гайд или онбординг.

Какие задачи решает

  • составить пошаговый обучающий урок по методологии Diataxis
  • исключить развилки и лишние варианты в руководстве для новичков
  • добавить блоки проверки ожидаемого вывода к каждому шагу
  • оформить вводное руководство в стиле совместной работы через «мы»

Примеры запросов агенту

  • Напиши вводный туториал по сборке простого веб-сервера для новичков.
  • Составь пошаговое руководство getting started для нашего CLI-инструмента.
  • Подготовь практический обучающий гайд по созданию первого плагина.

Как установить tutorial-docs

1Через Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill tutorial-docs -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/tutorial-docs/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о tutorial-docs

Как установить tutorial-docs в Claude Code?

Для установки выполните команду npx skills add existential-birds/beagle --skill tutorial-docs -a claude-code. Конфигурация запишется в ~/.claude/skills/tutorial-docs/SKILL.md.

Что делает tutorial-docs?

Скилл передаёт модели шаблон и правила Diataxis для обучающих руководств. Он требует показывать ожидаемый результат каждого действия и вести повествование от первого лица множественного числа.

Что нужно для работы tutorial-docs?

Скилл опирается на базовые правила формулировок из связки с docs-style. Внешние сервисы и API-ключи для него не требуются.

Исходный текст

SKILL.md · Apache-2.0
---
name: tutorial-docs
description: "Tutorial patterns for documentation - learning-oriented guides that teach through guided doing. Use when writing a tutorial, learning guide, getting-started or onboarding guide, beginner/introductory guide, or any learn-by-doing hands-on guide. Builds on the docs-style core writing principles."
user-invocable: false
---

# Tutorial Documentation Skill

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.

**Dependency:** Use this skill with `docs-style` for core writing principles. To confirm a tutorial is the right type — rather than a how-to, reference, or explanation — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

## Purpose & Audience

**Target readers:**
- Complete beginners with no prior experience
- Users who want to learn, not accomplish a specific task
- People who need a successful first experience with the product
- Learners who benefit from guided, hands-on practice

**Tutorials are NOT:**
- How-To guides (which help accomplish specific tasks)
- Explanations (which provide understanding)
- Reference docs (which describe the system)

## Core Principles (Diataxis Framework)

### 1. Learn by Doing, Not by Reading

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." |

### 2. Deliver Visible Results at Every Step

After each action, tell readers exactly what they should see. This confirms success and builds confidence.

```markdown
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>
```

### 5. Permit Repetition to Build Confidence

Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.

### 6. Write in the First-Person Plural

Diataxis prescribes the "we" voice for tutorials — "In this tutorial, we will build…", "Now we add…", "Let's check the output." It affirms the bond between teacher and learner: you are doing this *together*, and the teacher takes responsibility for the outcome. Reserve bare second-person imperatives ("Run this command") for the individual actions the reader performs; frame the journey itself with "we."

| Avoid | Prefer |
|-------|--------|
| "You will build a dashboard." | "In this tutorial, we'll build a dashboard." |
| "Next, configure the API." | "Now let's configure the API." |

## Tutorial Template

Use this structure for all tutorials:

```markdown
---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---

# Build Your First [Thing]

In this tutorial, we'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]

## Step 2: [Create your first thing]

[Next action with clear instruction]

```code
[code to add or modify]
```

Save the file. You should see [visible change].

<Note>
[Optional tip to prevent common mistakes]
</Note>

## Step 3: [Continue building]

[Continue with more steps, each producing visible output]

## Step 4: [Add the final piece]

[Bring it together with a final step]

You should now see [final visible result].

[Screenshot of completed project]

## What you've learned

In this tutorial, you:

- [Concrete skill 1 - what they can now do]
- [Concrete skill 2]
- [Concrete skill 3]

## Next steps

Now that you have a working [thing], you can:

- **[Tutorial 2 title]** - Continue learning by [next learning goal]
- **[How-to guide]** - Learn how to [specific task] with your [thing]
- **[Concepts page]** - Understand [concept] in more depth
```

## 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>
```

### The "You should see" Pattern

This is the most important pattern in tutorial writing. Use it constantly:

```markdown
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>
```

## Components for Tutorials

### Frame Component for Screenshots

Show what success looks like:

```markdown
<Frame caption="Your completed dashboard should look like this">
  ![Dashboard screenshot](/images/tutorial-dashboard.png)
</Frame>
```

### Steps Component for Procedures

For numbered sequences within a step:

```markdown
<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>
```

### Callouts for Guidance

```markdown
<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>
```

### Code with Highlighted Lines

Draw attention to what matters:

```markdown
```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
- [ ] Pre-publish gates (below) completed in order—not only self-reviewed

## Pre-publish gates

Run these **in order**. Start the next gate only after the previous **pass** is satisfied.

1. **Draft artifact** — The tutorial exists at a concrete path (file, branch, or CMS location). **Pass:** the artifact opens without guesswork.

2. **Observable outcomes** — **Pass:** every procedural step states what the reader should see next (command output, UI change, or named file)—not only what to do.

3. **Single path** — **Pass:** aside from prerequisite install links, the body does not branch into equivalent alternatives (“npm or yarn…”) unless you split into separate tutorials.

4. **Independent run** — Someone who did not write the draft follows the tutorial from a clean starting point. **Pass:** each step matches its promised outcome; any mismatch is fixed in the doc before publish (see “The Teacher Takes Responsibility” above).

## 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" |

For the full compass procedure and the other type distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

### 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](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[howto-docs](../howto-docs/SKILL.md)**: How-To guide patterns for task-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns

© existential-birds · Apache-2.0 · existential-birds/beagle

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
documentation mcollina Скилл documentation структурирует техническую документацию по фреймворку Diátaxis. Он помогает писать туториалы, инструкции how-to, справочники и концептуальные статьи без каши в структуре. CX Codex +1 2 000установок absolute-docs dhruvjainin Скилл absolute-docs для Claude Code структурирует техническую документацию по методологии Diátaxis. Помогает писать руководства, справочники, README и проводить аудит существующих страниц. CX Codex +1 171установок code-documentation-tutorial-engineer Seth Hobson Субагент code-documentation-tutorial-engineer превращает исходный код в пошаговые обучающие материалы и руководства по онбордингу. Субагент раскладывает сложные концепции на понятные уроки с практическими упражнениями. CX Codex ★ 42 780звёзд репо developer-docs-structure-audit Samuel Berthe Скилл developer-docs-structure-audit для Claude Code, Codex, Cursor и других сред проводит аудит информационной архитектуры документации. Находит страницы не на своём месте и пробелы в структуре по методологии Diátaxis. CX Codex +1 13 700установок tutorial-design NickCrew Скилл tutorial-design помогает проектировать пошаговые туториалы, воркшопы и практические руководства с контрольными точками и разбором частых ошибок. CX Codex +1 102установок documentation-writer официальный github Скилл documentation-writer для создания технической документации по фреймворку Diátaxis: туториалы, гайды, справки и объяснения. Предлагает структуру перед написанием. CX Codex +1 27 757установок

Из того же набора68

Весь набор →
shadcn-ui Учит агента строить UI-компоненты по паттернам shadcn/ui — CVA-варианты, составные компоненты, data-slot-атрибуты. CX Codex +1 358установок react-flow-code-review Скилл react-flow-code-review для Claude Code и Codex проверяет код на @xyflow/react по чек-листу: антипаттерны, лишние ре-рендеры, типы. Фиксирует тормоза графа и пересоздание нод. CX Codex +1 329установок langgraph-architecture Скилл langgraph-architecture для Claude Code помогает выбрать структуру LangGraph-приложения, схему состояния и подход к хранению данных. Сравнивает LangGraph с альтернативами и помогает проектировать системы агентов. CX Codex +1 283установок swiftui-code-review Скилл swiftui-code-review для Claude Code проверяет SwiftUI-код: композицию представлений, состояние, производительность и доступность. Разбирает файлы с @State, @Binding, @Observable и UI-кодом. CX Codex +1 277установок bubbletea-code-review Скилл bubbletea-code-review для Claude Code проверяет Go-код BubbleTea-проектов: архитектуру Elm, цикл Update и стили Lipgloss. CX Codex +1 270установок zustand-state Скилл zustand-state для Claude Code помогает создавать хранилища Zustand, выбирать данные селекторами, сохранять их в localStorage и подключать devtools. CX Codex +1 261установок dagre-react-flow Скилл dagre-react-flow настраивает автоматическую раскладку направленных графов в React Flow с помощью dagre. Помогает строить иерархические деревья и выравнивать узлы по направлениям. CX Codex +1 257установок adr-writing Скилл adr-writing для Claude Code, который оформляет архитектурные решения в документы ADR по шаблону MADR и проверяет их полноту по чек-листу E.C.A.D.R. Работает также в Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. CX Codex +1 254установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой