npx skills add https://github.com/existential-birds/beagle --skill tutorial-docs本技能提供遵循 Diataxis 框架编写有效教程的模式。教程是以学习为导向的内容,读者在教师的指导下通过实践进行学习。
目标读者:
教程不是:
教程通过行动而非解释来教学。读者应时刻在进行操作。
| 避免 | 推荐 |
|---|---|
| "REST API 使用 HTTP 方法来..." | "运行此命令进行您的首次 API 调用:" |
| "身份验证很重要,因为..." | "添加您的 API 密钥以进行身份验证:" |
| "仪表板包含几个部分..." | "在仪表板中点击 创建项目。" |
在每个操作之后,准确告诉读者应该看到什么。这可以确认成功并建立信心。
运行开发服务器:
npm run dev
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
您应该看到:
> Local: http://localhost:3000
> Ready in 500ms
在浏览器中打开 http://localhost:3000。您应该看到一个显示"Hello, World!"的欢迎页面。
教程不应提供替代方案。选择一种方式并完整地引导读者完成。
| 避免 | 推荐 |
|---|---|
| "您可以使用 npm、yarn 或 pnpm..." | "安装依赖项:" |
| "有几种配置方式..." | "创建一个配置文件:" |
| "可选地,您可能想要..." | [完全省略可选步骤] |
如果读者失败了,那就是教程的失败。预见问题并加以预防。永远不要责怪读者。
<Warning>
运行此命令前,请确保您在项目目录中。
如果看到"command not found",请返回步骤 2 验证安装。
</Warning>
在略有不同的上下文中重复类似的操作有助于巩固学习。不要试图追求效率。
所有教程都使用此结构:
---
title: "构建您的第一个 [事物]"
description: "通过构建一个可工作的 [事物] 来学习 [产品] 的基础知识"
---
# 构建您的第一个 [事物]
在本教程中,您将构建一个 [具体的交付成果]。最终,您将拥有一个可以 [执行某些可见操作] 的可工作的 [事物]。
<Note>
完成本教程大约需要 [X] 分钟。
</Note>
## 您将构建什么
[最终结果的截图或图表]
一个 [具体交付成果的简要描述],它:
- [可见能力 1]
- [可见能力 2]
- [可见能力 3]
## 先决条件
开始之前,请确保您有:
- [最低要求 1 - 如果需要,链接到安装指南]
- [最低要求 2]
<Tip>
对 [先决条件] 不熟悉?[外部资源链接] 有一个快速设置指南。
</Tip>
## 步骤 1: [设置您的项目]
[第一个操作 - 总是从能产生可见输出的内容开始]
```bash
[命令]
您应该看到:
[预期输出]
[简要确认这意味着什么]
[带有清晰说明的下一步操作]
[要添加或修改的代码]
保存文件。您应该看到 [可见的变化]。
[继续更多步骤,每一步都产生可见输出]
[通过最后一步将所有内容整合在一起]
您现在应该看到 [最终的可见结果]。
[完成项目的截图]
在本教程中,您:
现在您有了一个可工作的 [事物],您可以:
## 写作原则
### 标题约定
* **以行动结果开头**:"构建您的第一个...", "创建一个...", "部署您的..."
* 专注于他们将制作什么,而不是他们将学到什么
* 具体化:"构建一个聊天应用",而不是"学习实时消息传递"
### 步骤结构
1. **以行动为先导** - 不要在做之前解释
2. **准确展示要输入或点击的内容** - 没有歧义
3. **每一步之后确认成功** - "您应该看到..."
4. **保持步骤简短** - 每个步骤一个可见变化
### 管理先决条件
教程面向初学者,因此最小化先决条件:
```markdown
## 先决条件
- 一台装有 macOS、Windows 或 Linux 的计算机
- 一个文本编辑器(我们推荐 VS Code)
- 15 分钟时间
<Tip>
您不需要任何编程经验。本教程会逐步解释所有内容。
</Tip>
这是教程写作中最重要的模式。经常使用它:
点击 保存。您应该看到一个绿色的对勾出现在文件名旁边。
运行测试:
npm test
您应该看到:
PASS src/app.test.js
✓ renders welcome message (23ms)
Tests: 1 passed, 1 total
预见失败并引导读者回到正轨:
<Warning>
如果看到"Module not found",请确保您保存了步骤 2 中的文件。
返回步骤 2 并验证导入语句是否完全匹配。
</Warning>
展示成功的样子:
<Frame caption="您完成的仪表板应如下所示">

</Frame>
用于步骤内的编号序列:
<Steps>
<Step title="打开设置面板">
点击右上角的齿轮图标。
</Step>
<Step title="找到 API 部分">
向下滚动到 **开发者设置**。
</Step>
<Step title="生成密钥">
点击 **创建新密钥** 并复制显示的值。
</Step>
</Steps>
<Note>
如果颜色在您的屏幕上看起来不同,请不要担心。
我们将在下一步中自定义主题。
</Note>
<Warning>
请确保在继续之前保存文件。
没有此更改,下一步将无法工作。
</Warning>
<Tip>
您可以按 Cmd+S (Mac) 或 Ctrl+S (Windows) 快速保存。
</Tip>
引起对重要内容的注意:
function App() {
return (
<h1>Hello, World!</h1>
<p>Welcome to your first app.</p>
);
}
请参阅 references/example-weather-api.md 查看一个完整的示例教程,演示了上述所有原则。该示例构建了一个获取真实 API 数据的天气仪表板。
发布前,请验证:
| 用户心态 | 文档类型 | 示例 |
|---|---|---|
| "我想学习" | 教程 | "构建您的第一个聊天机器人" |
| "我想做 X" | 操作指南 | "如何配置 SSO" |
| "我想理解" | 解释说明 | "我们的缓存如何工作" |
| "我需要查找 Y" | 参考文档 | "API 端点参考" |
| 方面 | 教程 | 操作指南 |
|---|---|---|
| 目的 | 通过实践学习 | 完成特定任务 |
| 受众 | 完全初学者 | 有一定经验的用户 |
| 结构 | 具有一条路径的线性旅程 | 实现目标的步骤 |
| 选择 | 无 - 一种规定方式 | 可能展示替代方案 |
| 解释 | 最少 - 行动重于理论 | 最少 - 专注于步骤 |
| 成功 | 读者学习并获得信心 | 读者完成他们的任务 |
| 长度 | 更长,更多手把手指导 | 更短,更直接 |
每周安装次数
85
仓库
GitHub 星标数
41
首次出现
2026年1月24日
安全审计
已安装于
gemini-cli65
opencode64
codex64
claude-code62
cursor59
github-copilot58
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].
[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:
[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
Tutorials are for beginners, so minimize prerequisites:
## 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
Weekly Installs
85
Repository
GitHub Stars
41
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
gemini-cli65
opencode64
codex64
claude-code62
cursor59
github-copilot58
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
ULTRAQA 自主质量保证循环工具:自动化测试、构建、代码规范检查与修复
218 周安装
Vuetify0 无头组件库 - Vue 3 组合式函数与无样式UI构建块
219 周安装
AWS Serverless 开发指南:Lambda 函数与 API Gateway 集成模式最佳实践
216 周安装
Simplify代码简化工具 - 提升代码清晰度、一致性和可维护性的AI助手
222 周安装
GitHub CLI (gh) 使用指南:高效管理仓库、PR、议题与API调用
212 周安装
Cheerio HTML解析教程:Node.js网页抓取与DOM操作指南
214 周安装