# Docs Companion Examples

> How to commission and verify a page's companion example files — the standalone runnable Scala a page pulls in with mdoc:embed or SourceFile.print. Use when a documentation page embeds example files rather than relying only on inline mdoc blocks, to delegate the build and check what came back.

- Skill: `zio/docs-companion-examples` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zio/docs-companion-examples`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zio/docs-companion-examples/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zio (https://skillmd.com/u/zio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zio/docs-companion-examples

---


# Companion Examples

A page's runnable examples come in two forms. **Inline** mdoc blocks compile as part of the page and
need nothing here. **Embedded** files — pulled in with `mdoc:embed:<path>` or `SourceFile.print` from a
tutorial's "Putting It Together" or a reference page's "Running the Examples" — are real `.scala` files
that must exist on disk before mdoc runs, in their own sbt build.

Delegate the build to the **`docs-examples-builder`** agent with the `Task` tool — it must NOT share
your conversation, so its only knowledge of the page is what you tell it. The agent already knows the
decoupled sbt build topology, file templates, and the compile/lint/self-check procedure; give it only
the page-specific parameters:

```
Task(
  description: "Build companion examples for <page-id>",
  subagent_type: "documentation:docs-examples-builder",
  prompt: "Page: <path to the page being documented>
           Embeds this page declares: <every mdoc:embed:<path> or SourceFile.print path it names,
             each of which must end up at exactly that path>
           Requirement: every example must print meaningful output when run, not just compile."
)
```

## Ordering

Commission the examples **before** mdoc verification. An `mdoc:embed:<path>` block fails outright when
the file it names is absent, so a page that embeds examples cannot pass mdoc until they exist.

For a module reference, prefer ONE module-level example set that exercises several types together over
one set per type — the cross-type workflow is what a module page is for.

## Verifying what came back

The delegation is done when every embedded path exists and the examples leaf compiles and runs. Check:

- each `mdoc:embed:<path>` or `SourceFile.print` call in the page resolves to a real file,
- the example code traces to the page's own blocks — nothing invented beyond glue,
- the leaf built and each example ran, rather than only compiling.

If mdoc later reports an unresolved embed, the file is missing or at the wrong path — fix the path or
re-commission it rather than deleting the embed to make the page compile.