Explore Skill

The Explore Skill (atelier-explore) creates narrative walkthroughs that are grounded in your project. It writes the result to .walkthroughs/{slug}.md with views: walkthrough frontmatter so Atelier opens it in walkthrough mode.

Use it when you want a durable, clickable explanation of how something works, not just a quick chat answer. Each walkthrough links headings, prose, diagrams, and supporting references back to the source files the agent inspected.

When to use

• You want an onboarding tour of a codebase, subsystem, or important folder
• You want to understand a feature end to end across code and docs
• You want to trace a route, command, event handler, or other entry point through the code
• You want to map how data moves through a set of transforms
• You want a guided reading of an existing spec, ADR, or design document
• You want an architecture map or runnable playbook for setup, deployment, debugging, or rollback

When not to use

• You only need a quick answer in chat
• You are planning implementation work from a TODO item — use the Planning Skill
• You are revising an annotated markdown document — use the Revise Skill

Arguments

The skill is intentionally interactive and does not require formal arguments. Start it with /atelier-explore, then answer the scoping questions about what to cover, how deep to go, and whether to follow the system top-down or trace backward from a result.

What it does

1. Scopes the walkthrough — Asks clarifying questions about the subsystem, feature, document, or workflow you want explained.
2. Chooses a walkthrough type — Selects the best format for the reader’s goal: onboarding tour, feature deep-dive, call trace, data flow, document walkthrough, architecture map, or playbook.
3. Finds source material — Identifies the code files, docs, sections, and entry points the walkthrough should cover.
4. Grounds every section — Uses code and document grounding agents to pull source-backed passages with text-fragment links.
5. Writes a walkthrough file — Creates .walkthroughs/{slug}.md with views: walkthrough frontmatter.
6. Links each step to source — Makes H2 headings deep-link to the most important source target for that step, so Atelier can auto-open the relevant file as you move through the walkthrough.
7. Adds diagrams where helpful — Uses Mermaid diagrams for architecture, call traces, data flow, or playbooks when a visual map makes the explanation easier to follow.

Walkthrough types

Type	Use it for
Onboarding tour	A first look at a codebase, subsystem, package, or important folder
Feature deep-dive	A feature explained end to end across implementation and supporting docs
Call trace	A top-down trace from an entry point such as a route, command, or event handler
Data flow	The shape of data as it moves through parsing, validation, transforms, storage, or rendering
Doc walkthrough	A guided tour of an existing spec, ADR, design doc, or other markdown document
Architecture map	A high-level system view with components, boundaries, and interactions
Playbook	A runnable operational guide for setup, deploy, debug, rollback, or maintenance work

Output format

Explore writes markdown files under .walkthroughs/. Every file starts with walkthrough frontmatter:

---
views: walkthrough
title: OAuth Login Flow
---

Each major step is an H2 heading. By default, the heading links to the single most important source target for that step:

## [handleRequest](./src/handler.ts#:~:text=export%20async%20function%20handleRequest,return%20response)

Supporting links stay in the prose beneath the heading. The skill uses text-fragment links instead of line-number links so references survive nearby edits.

Invocation

Run the slash command directly from your coding agent:

/atelier-explore

After the walkthrough is created, the agent reports the generated .walkthroughs/{slug}.md path and summarizes the sections it wrote.