> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com.pgm.c5nprx.cc/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Subtext Skills: Agent Workflows for Session Review
> Subtext skills are slash commands that teach your agent structured workflows — from reading the event map to explaining what happened in a session.
Subtext skills are slash commands you type in your agent's chat. Each skill injects a structured prompt that teaches your agent what tools exist, in what order to call them, and what constitutes a complete result. Instead of writing out a multi-step investigation request from scratch every time, you invoke a skill and your agent knows exactly what to do.
There are two kinds of skills: **workflow skills** and **atomic skills**. Workflow skills like `/subtext:subtext-review` describe an end-to-end task — open a session, zoom to the moments that matter, explain what happened. Atomic skills like `/subtext:subtext-shared` and `/subtext:subtext-session` are building blocks — they teach the agent a single layer of context (conventions, tool catalog, usage patterns) that workflow skills compose together.
A third group covers [Sightmap](https://docs.sightmap.org) — authoring the `.sightmap/` corpus that gives your components names, and feeding it into a review. Those skills ship with the plugin; see [Sightmap skills](#sightmap-skills) below.
***
## Workflow skills
Workflow skills are the ones you invoke directly to get something done.
### `/subtext:subtext-review`
The main session review workflow. When you invoke `/subtext:subtext-review`, your agent runs a complete investigation: it lists available sessions, opens the one you care about, reads the event map, zooms to the moments that matter, captures snapshots at key timestamps, and produces a plain-English explanation of what happened.
**How to invoke it:**
Type `/subtext:subtext-review` in your agent's chat, followed by enough context to identify the session or the problem. For example:
```
/subtext:subtext-review — check the session from the checkout failure this morning
```
The agent will:
1. Call `review-list-sessions` to find recent sessions and match against your description.
2. Call `review-open` on the best match, read the event map, and orient itself.
3. Call `review-summary` for a quick first pass.
4. Call `review-zoom` one or more times, narrowing in on the intervals the event map flagged as significant.
5. Call `review-snapshot` at key timestamps to capture visual evidence.
6. Produce an explanation — what the user did, what the application did in response, where it diverged from expected behavior, and a root-cause hypothesis.
7. Call `review-close` and record its conclusion.
**Sample agent conversation:**
```
You: /subtext:subtext-review — the payment form is throwing a validation error
that users are hitting, latest session
Agent: I'll open the most recent session on the checkout page.
[calls review-list-sessions]
Found 3 sessions on /checkout from the past 2 hours.
Opening the most recent one (recorded 14 minutes ago).
[calls review-open → reads event map]
The event map shows two payment attempts. The second one fired
a `form:error` event at 01:02.4. Let me zoom in.
[calls review-zoom with window 55000–75000ms, high resolution]
The expiry field emitted a blur event with an empty value at
01:01.8, 600ms before the error. Taking a snapshot.
[calls review-snapshot at 62400ms]
The snapshot shows the CheckoutForm with the expiry field
highlighted in red and an inline message "Expiry date required."
Root cause: The expiry field's required validation only triggers
on blur, not on submit. When the user skips the field entirely and
clicks Pay, blur never fires, the field stays invalid silently,
and the submit handler produces the error without surfacing it
until the second attempt.
Suggested fix: add explicit validation in the submit handler for
all required fields, not just on blur. See CheckoutForm.tsx:88.
[calls review-close with conclusion]
```
You don't need to specify a session ID. Describe the problem in natural language — "the error users hit on the pricing page yesterday afternoon" — and the agent will match it against the available sessions.
***
## Atomic skills
Atomic skills are the foundation that workflow skills are built on. You rarely invoke them directly, but understanding what they contain helps when you want to extend a workflow or debug why an agent isn't using tools correctly.
### `/subtext:subtext-shared`
The foundation skill. Every other skill depends on it. `/subtext:subtext-shared` teaches your agent the MCP conventions Subtext uses: how handles work, how to interpret return values, what error shapes to expect, and the security rules that govern what the agent is and isn't allowed to do with session data.
**When to invoke it directly:** If your agent seems confused about MCP conventions — ignoring return values, passing wrong argument types, or not respecting privacy rules — invoke `/subtext:subtext-shared` to re-establish the baseline.
```
/subtext:subtext-shared
```
* MCP handle lifecycle: how session handles are acquired, used, and released
* Argument conventions: types, required vs optional parameters, error handling
* Security rules: what data may be passed to external tools, what must stay local
* Privacy baseline: form inputs are masked by default; the agent must not attempt to recover masked values
***
### `/subtext:subtext-session`
The session replay atomic skill. `/subtext:subtext-session` teaches your agent the complete catalog of `review-*` tools — what each one does, when to reach for it, and usage patterns that keep investigations efficient.
**When to invoke it directly:** If your agent knows MCP conventions but is unsure which review tool to use for a given step, invoke `/subtext:subtext-session` to give it the tool-level context it needs.
```
/subtext:subtext-session
```
* Full catalog of `review-*` tools with parameter descriptions and return shapes
* Recommended call order for a full investigation
* When to use `review-summary` vs `review-zoom` vs `review-snapshot`
* Resolution and time-window guidance for `review-zoom`
* How to interpret the event map returned by `review-open`
* How sightmap enrichment changes snapshot output
***
## Sightmap skills
A [Sightmap](https://docs.sightmap.org) is the semantic map of your UI — YAML in `.sightmap/`, checked into your repo, naming your app's views, components, and API requests. Feed it to a review and snapshots come back as `AddToCartButton (src/components/AddToCart.tsx)` rather than a CSS selector.
Three skills cover it: one that connects an existing corpus to session review, and two that build and verify the corpus itself. All three ship with the plugin — there's nothing extra to install to get the skills.
### `/subtext:subtext-sightmap`
The bridge between a project's `.sightmap/` corpus and the `review-*` tools. Invoke it when your project has a `.sightmap/` directory and you want snapshots and signals annotated with component names.
**When to invoke it directly:** at the start of a review in a sightmapped project, before the agent's first `review-snapshot` — the corpus has to be uploaded before anything is read back.
```
/subtext:subtext-sightmap
```
* The side-band upload path: `review-open` returns a single-use `sightmap_upload_url`, and a bundled collector script POSTs the whole corpus to it before the first `review-zoom` or `review-snapshot`
* The inline fallback — `review-open`'s `sightmap` array — for small, hand-authored, already-flattened definition sets
* Keeping the checked-in YAML as the source of truth rather than pasting one-off definitions
### `/subtext:sightmap-authoring`
Build and maintain the corpus. This is where the full `.sightmap/` schema reference lives — components, views, requests, and memory — along with the iterative loop for getting coverage to zero orphaned nodes.
**When to invoke it directly:** when you're creating a sightmap from scratch, adding a page to an existing one, or a snapshot came back with generic a11y roles where you expected component names.
```
/subtext:sightmap-authoring
```
* The `.sightmap/` YAML schema: components, views, requests, and memory
* Seeding a corpus from a live site or from the codebase
* The snapshot → coverage → validate → lint loop, and how to diagnose orphaned nodes
* Property extraction, cross-page promotion of shared components, and the known limitations
### `/subtext:sightmap-browser`
Drive a local Chrome session with your corpus layered onto the live page. Use it to read the running app's state as an annotated component tree, and to act on elements by component identity rather than a CSS selector.
**When to invoke it directly:** while authoring, to verify coverage against the real page before and after an edit.
```
/subtext:sightmap-browser
```
* Starting, navigating, and managing a browser session
* Annotated component snapshots for reading page state
* Interacting by component ID or by CSS-shaped component query over sightmap components and extracted properties
* Console and network inspection for debugging
`sightmap-authoring` and `sightmap-browser` are vendored from the open-source [`@sightmap/sightmap`](https://docs.sightmap.org) package at a pinned version, so the guidance in your plugin matches a known release of the toolchain. Both drive the `sightmap` CLI against a local Chrome — install it with `npm install -g @sightmap/sightmap` if it isn't already on your PATH. This is separate from the cloud-hosted browser in [Verify](/docs/verify/live-browser), which reads the same corpus but needs no local install.
***
## How workflow and atomic skills relate
The `/subtext:subtext-review` workflow skill composes `/subtext:subtext-shared` and `/subtext:subtext-session`. When you invoke `/subtext:subtext-review`, the agent effectively gets all three layers of context at once:
```
/subtext:subtext-review
└── /subtext:subtext-shared (MCP conventions, security rules)
└── /subtext:subtext-session (review-* tool catalog, usage patterns)
└── review workflow (end-to-end investigation steps)
```
You can invoke the atomic skills independently to refresh a specific layer without running the full workflow. This is useful if you're building a custom harness and want to give your agent tool knowledge without prescribing a specific investigation flow.
Skills are delivered as MCP prompts, not system prompt injections. They are scoped to the conversation turn in which you invoke them — they don't persist across sessions automatically. If you start a new chat, invoke the skill again.