# Docs Examples

> Shared procedure for creating and documenting companion examples. Covers directory structure, file templates, example creation, compilation, linting, and embedding with SourceFile. Used by docs-data-type-ref, docs-module-ref, docs-how-to-guide, and docs-tutorial.

- **Type:** Skill
- **Install:** `agentstack add skill-zio-zio-skills-docs-examples`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zio](https://agentstack.voostack.com/s/zio)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **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/plugins/documentation/skills/docs-examples

## Install

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

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

## About

## Setup Example Sub-module

Add to root `build.sbt`, for example if the you are creating examples for a webauthn guide:

```scala
lazy val `zio-http-example-webauthn` =
  RootProject(file("zio-http-example-webauthn"))

lazy val root = (project in file("."))
  .aggregate(
    // other sub-modules
    `zio-http-example-webauthn`
  )
```

Inside the example project directory, create a standard Scala project structure, including a `build.sbt` with necessary dependencies.

## Creating Example Files

### Step 1: Directory and Package Structure

Create a package directory matching the following pattern:

```
/src/main/scala//
```

Where `` is one of:
- `-examples` (for module references, e.g., `http-model-examples`)
- `-examples` (for guides and tutorials, or integration examples spanning multiple modules)

**Name conversion rule**: Drop hyphens. e.g.:
- `query-dsl-sql` → `querydsl` (lowercase, hyphens removed)
- `http-model` → `httpmodel`
- `scope-resource-management` → `scoperesourcemanagement`

### Step 2: Example File Structure

Create **one Scala file per major step/concept/use case**, plus a final file for the complete example. Each file should be a standalone runnable program, either an `object` extending `App` or a Scala 3 `@main def` function.

**Naming convention depends on document type:**

| Document Type | File Naming |
|---------------|------------|
| How-to guides | `Step1BasicExample.scala`, `Step2AdvancedExample.scala`, ..., `CompleteExample.scala` |
| Tutorials | `Concept1Example.scala`, `Concept2Example.scala`, ..., `CompleteExample.scala` |
| Data type refs | `BasicUsage.scala`, `AdvancedPatterns.scala`, `CompleteExample.scala` (or descriptive names like `CompleteHttpRequest.scala`) |
| Module refs | `MultiTypeComposition.scala`, `CommonPattern1.scala`, ..., `CompleteExample.scala` (titles emphasizing multi-type usage) |

Create 3-5 files total (feel free to write more examples if number of concepts warrants it).

### Step 3: Example File Template

Each example file follows this pattern:

For Scala 3:

```scala
package 

import 

/**
 *  — Step/Concept/Pattern: 
 *
 * 
 *
 * Run with: sbt "/runMain ."
 */
@main def (): Unit = {
   // Example code
}
```

For Scala 2.13:

```scala
package 

import 

/**
 *  — Step/Concept/Pattern: 
 *
 * 
 *
 * Run with: sbt "/runMain ."
 */
object  extends App {
   // Example code
}
```

### Step 4: The Complete Example

The final example file (`CompleteExample.scala` or descriptively-named equivalent like `CompleteHttpRequest.scala`) must contain the **entire "Putting It Together" or most complex code block** from the document, wrapped in a runnable program (either a Scala 3 `@main def` function or a Scala 2.13 `object` extending `App`). This is the most important example file.

### Step 5: Verify Examples Compile

After creating all example files, verify they compile:

```bash
sbt "/compile"
```

Fix any compilation failures before proceeding. The examples must compile successfully.

### Step 6: Lint Check (Mandatory Before Integration)

After all examples compile, stage them in git, then run Scalafmt:

```bash
git add /src/main/scala/**/*.scala
sbt fmtChanged
```

If any files were reformatted, commit them immediately:

```bash
git add -A
git commit -m "docs(): apply scalafmt to examples"
```

Verify the CI lint gate locally:

```bash
sbt check
```

**Success criterion**: Zero formatting violations reported.

---

### Step 7: Documenting Examples

#### When Examples Use SourceFile Embedding

For data type references and module references where examples need detailed documentation:

Place the "Running the Examples" section at the end of the documentation, after all type/module documentation. Use this template:

```
    ## Running the Examples
    
    All code from this guide is available as runnable examples in the `` module.
    
    **1. Clone the repository and navigate to the project:**
    
    ```bash
    git clone https://github.com/zio/.git
    cd 
    ```
    
    **2. Run individual examples with sbt:**
    
    ### 
    
    
    
    ```scala mdoc:passthrough
    import docs.SourceFile
    
    SourceFile.print("/src/main/scala//.scala")
    ```
    
    ([source](https://github.com/zio//blob/main//src/main/scala//.scala))
    
    ```bash
    sbt "/runMain ."
    ```
    
    ### 
    
    
    
    ```scala mdoc:passthrough
    import docs.SourceFile
    
    SourceFile.print("/src/main/scala//.scala")
    ```
    
    ([source](https://github.com/zio//blob/main//src/main/scala//.scala))
    
    ```bash
    sbt "/runMain ."
    ```
```

**Optional parameters:**
- `lines = Seq((from, to))` — include only specific line ranges (1-indexed)
- `showLineNumbers = true` — render with line numbers
- `showTitle = false` — suppress the file path title

#### When Examples Use Basic Shell Commands

For how-to guides and tutorials where examples are listed simply:

```markdown
    ## Running the Examples
    
    All code from this guide/tutorial is available as runnable examples in the `` module.
    
    **1. Clone the repository and navigate to the project:**
    
    ```bash
    git clone https://github.com/zio/.git
    cd 
    ```
    
    **2. Run individual examples with sbt:**
    
    ```bash
    # Step/Concept 1: 
    sbt "/runMain ."
    
    # Step/Concept 2: 
    sbt "/runMain ."
    
    # ...additional steps/concepts...
    
    # Complete example
    sbt "/runMain ."
    ```
    
    **3. Or compile all examples at once:**
    
    ```bash
    sbt "/compile"
    ```
```

    
- List **every `App` object** in the examples module, one entry per object
- For each entry: use a `###` heading (simple, concise title), followed by a short descriptive paragraph
- The paragraph explains what the example demonstrates and the use case/pattern it covers
- For modules: emphasize which types compose in each example
- Embed full source with `SourceFile.print` (keeps docs and examples in sync automatically)
- Include source link and run command
- Keep the two numbered steps (clone, run individually) in that order

## 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-examples
- 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%.