# Docs Tutorial

> Write a tutorial for newcomers learning a topic in a ZIO library. Tutorials teach concepts step-by-step in a linear path for learning-oriented, not task-oriented, purposes. Use when writing comprehensive learning guides.

- **Type:** Skill
- **Install:** `agentstack add skill-zio-zio-skills-docs-tutorial`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zio](https://agentstack.voostack.com/s/zio)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [zio](https://github.com/zio)
- **Source:** https://github.com/zio/zio-skills/tree/main/writer-assistant/skills/docs-tutorial

## Install

```sh
agentstack add skill-zio-zio-skills-docs-tutorial
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tutorial: Conceptual Overview

A tutorial is **learning-oriented** — it builds mental models for newcomers encountering a topic for the first time. It is not a reference page (exhaustive API) or how-to guide (task completion).

## Core Properties

- **Targets newcomers**: assume no prior knowledge of the topic
- **Linear path**: no branching, no "alternatively" — one path, followed to completion
- **One concept per section**: each section introduces exactly one new idea
- **Annotated code**: every code block followed by line-by-line bullet explanation
- **Intermediate output**: show results after meaningful steps so learner can verify progress
- **Warm tone**: "Welcome", "Let's", "notice that", "try changing X to see Y"
- **Present tense**: "we learn", "we see", "we observe"
- **Recap at end**: "What You've Learned" mirrors the opening learning objectives

## 7-Section Structure

1. **Introduction** — who it's for, learning objectives, section outline
2. **Background / Big Picture** (optional) — conceptual framing, no code
3. **Concept sections** (3–6) — one concept each, code + annotation + output. When companion examples are requested, each section's code block stays an inline `mdoc` block (auto-rendered output is required here — `mdoc:embed` cannot show it), but the corresponding companion `.scala` file must copy that code **verbatim**, not re-derive it from the prose.
4. **Putting It Together** — complete runnable example combining all concepts. When companion examples are requested, do not paste this code inline — write it directly to `CompleteExample.scala` and embed it with `mdoc:embed` (output rendering isn't needed here, so embedding the file directly eliminates the duplication entirely).
5. **Running the Examples** — one `###` per example: narrative, embedded source, observe note, run command. `CompleteExample.scala` is already embedded in "Putting It Together" — do not embed its source a second time here; give it narrative + observe note + run command only.
6. **What You've Learned** — bullet recap mirroring learning objectives
7. **Where to Go Next** — links to how-to guides and reference pages

## Quality Gate

Before submitting, work through **[CHECKLIST.md](./CHECKLIST.md)** — 38 items across Content Quality, Technical Accuracy, Companion Examples, Running the Examples, and Style and Integration.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zio](https://github.com/zio)
- **Source:** [zio/zio-skills](https://github.com/zio/zio-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zio-zio-skills-docs-tutorial
- Seller: https://agentstack.voostack.com/s/zio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.