# Session-to-skill (skill compilation)

> Session-to-skill extraction — skill compilation, in Reelier's vocabulary — is the practice of turning a finished agent session into a reusable skill: the transcript of what the agent did is parsed, the repeatable tool calls are lifted out, and the result is compiled into a standalone artifact, typically a SKILL.md file, that can be reviewed, versioned, and run again without re-deriving the plan. It treats the session as source material rather than a disposable event: the work the agent already paid for once — reasoning its way to a working tool-call sequence — becomes a procedure. Extractors split into two families: LLM review, where a model reads the transcript and writes up the procedure it found, and deterministic compilation, where a parser lifts the typed tool calls out mechanically and no model is involved at all.

Markdown twin of https://www.reelier.com/learn/skill-compilation — one entry in Reelier's glossary of agent-replay terms. The blockquote above is the canonical definition; quote it with the link.

## Two extraction families: LLM review and deterministic compilation

The vocabulary comes from two places. Anthropic's Agent Skills gave the ecosystem the artifact: a SKILL.md an agent discovers and loads — organized instructions and resources, versioned in a repo like any other code. MindStudio named the pipeline, calling it a session-to-skill extractor: a workflow that reads finished agent sessions and pulls out the procedures worth keeping. Their extractor is the LLM-review kind — a model reads the filtered transcript, answers a structured set of questions about it, and writes up what it found.

Reelier sits in the second family. `reelier from-session` parses the transcript your agent already wrote (Claude Code's `~/.claude/projects` JSONL is the native format), filters it to the tool calls that can be re-executed, and compiles those into a SKILL.md with an assertion on every step that recorded a clean result — steps that failed during recording stay assertion-less and are flagged as open questions instead of being papered over. Compilation is a mechanical transform of the recording; it makes zero LLM calls.

The two families produce different artifacts. Model review produces instructions — prose the next agent run loads and reasons over, which generalizes but still spends tokens at execution time, and which describes the session rather than replaying it. Deterministic compilation produces an executable recording — typed JSON requests and responses that re-run without a model in the loop. Reelier calls its flavor skill compilation to keep that distinction visible: the output is a program you can run, and the recorded session is its provenance.

## The honesty filter: what a session gives up on the way to a skill

Most of a session cannot become a replayable skill, and an extractor that hides this is overselling. Reelier's classifier is default-deny: its own `http.get`/`http.post` builtins and MCP tool calls (`mcp__server__tool`) are replayable; every agent-native tool — `Bash`, `Read`, `Edit`, `Write`, `Grep`, subagent dispatch — is skipped, with the reason printed per tool. An edit-heavy coding session compiles to nothing, and `from-session` says so instead of inventing steps.

What survives the filter gets classified by effect — read, idempotent-write, or destructive, with unrecognized verbs falling through to destructive until a human reviews them. The compiler then reports what it wrote (step, assertion, and bind counts, plus which MCP servers the skill depends on), warns when replaying would re-fire side effects, and lists open questions instead of guessing: a literal repeated across steps that wants to be a variable, a step that failed during recording, a verb it could not classify.

Finding candidate sessions is its own command: `reelier scan` walks the agent history directories on your machine — Claude Code's `~/.claude/projects` natively, plus the Codex, Windsurf, and OpenClaw dirs — and ranks sessions by replay-worthiness. Cursor is absent from that list on purpose: it keeps history in a SQLite database, so there is no history scan for it. On Cursor you capture at the proxy instead — `reelier mcp --wrap` fronts the MCP server and records every call losslessly while the job runs once.

## Limits: what compiles is the work, not the judgment

A compiled skill freezes the tool calls, not the reasoning that produced them. Steps that need fresh judgment on every run — triage, synthesis, prose — do not compile into anything replayable. Reelier leaves those to a model, and only when asked: escalation during replay is opt-in and BYOK, in levels, and at the default `--max-level 0` an LLM client is never even constructed.

Expect the compiled skill to be side-effectful, because sessions are. In the measured corpus behind Reelier's launch writing, only 1.1% of scanned sessions were read-only end-to-end, and the receipt below — 15 of 16 extracted steps carrying side effects — shows the finding in the wild. That is why replay is read-only by default, with recorded writes never re-firing without `--allow-writes`, and why a freshly compiled skill is a draft: markdown you review, trim, and parameterize before it goes anywhere near a schedule. The compiler's open-questions list is the review agenda, printed for you.

## A real receipt

The output below is a real session-to-skill compilation, not a mockup: `reelier from-session` run against a real Claude Code transcript from this machine's history — an SEO-check session mixing PostHog queries and browser checks with edits and shell — using the published CLI (`npx -y reelier@latest`, resolved to `reelier@0.13.0`) on 2026-07-21. Everything the extractor did is on the receipt: the default-deny filter naming all 109 calls it refused, the side-effect warning, and the open questions it raised instead of guessing.

```
npx -y reelier@latest from-session c72387c6-fad1-4c81-a65c-7bec7bd727f5.jsonl --name posthog-seo-pull --out posthog-seo-pull.skill.md

Scanned c72387c6-fad1-4c81-a65c-7bec7bd727f5.jsonl: 16 replayable call(s) found.

Skipped 109 non-replayable/unresolved tool call(s):
  - ToolSearch x6
    'ToolSearch' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - Bash x71
    'Bash' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - WebFetch x6
    'WebFetch' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - WebSearch x2
    'WebSearch' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - Agent x5
    'Agent' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - Write x3
    'Write' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - Read x4
    'Read' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - Edit x9
    'Edit' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.
  - SendMessage x3
    'SendMessage' is a Claude Code native tool (file/shell/search/subagent action), not one of Reelier's own builtins (http.get/http.post) or an MCP server tool call — it can't be deterministically replayed, so it's never compiled into a skill.

Wrote posthog-seo-pull.skill.md
  steps:   16
  asserts: 14
  binds:   0
  MCP servers used: mcp-registry, posthog, Claude_Browser, plugin_playwright_playwright

⚠ 15 of 16 steps are side-effectful (create/update/delete/write) — replaying re-executes those side effects. Reelier replays best on read-only / data-pull workflows.
  exec, exec, exec, preview_start, preview_start, browser_navigate, browser_resize, browser_evaluate, browser_evaluate, browser_evaluate, browser_navigate, browser_evaluate, browser_evaluate, browser_resize, browser_evaluate

Open questions (7):
  - Step 5: Value "https://crm-git-feat-seo-internal-links-maxime-houles-projects.vercel.app/alternatives" appears literally in steps 5, 6, 7 and was never found in any prior result — consider promoting it to an {{input}} variable instead of repeating it.
  - Step 5: this step failed during recording — decide whether it belongs in the skill.
  - Step 6: this step failed during recording — decide whether it belongs in the skill.
  - Step 7: verb unrecognized — downgraded to destructive until you review.
  - Step 8: verb unrecognized — downgraded to destructive until you review.
  - Step 12: verb unrecognized — downgraded to destructive until you review.
  - Step 15: verb unrecognized — downgraded to destructive until you review.
```

Run by the author on 2026-07-21 in a scratch directory, on a copy of `~/.claude/projects/<project>/c72387c6-fad1-4c81-a65c-7bec7bd727f5.jsonl` (Claude Code's native transcript format). Output verbatim and unedited. The compiled `posthog-seo-pull.skill.md` stayed a draft — 15 of its 16 steps are side-effectful, which is exactly what the review pass is for.

## FAQ

**Is a compiled Reelier skill the same thing as an Anthropic Agent Skill?**

Same ecosystem, same filename convention, different content. An Agent Skill is a folder of instructions and resources a model loads and reasons over at run time. A Reelier SKILL.md is an executable recording: steps, typed arguments, and assertions that re-execute without a model. Both live in your repo as reviewable markdown; only the recording replays at 0 LLM tokens.

**Does extracting a skill from a session call a model?**

In Reelier, no. `reelier from-session` (from a scanned transcript) and `reelier compile` (from a recorded trace) are deterministic transforms — parse, filter, compile, render — and make zero LLM calls. LLM-review extractors work the other way: a model reads the session and writes the procedure. The trade cuts both ways — mechanical compilation is free and exact but captures only what can re-execute; model review can capture fuzzier know-how but spends tokens and can misstate what happened.

**My best sessions are full of shell commands and file edits — why does from-session find nothing?**

Because those cannot be deterministically re-executed, and Reelier refuses to pretend. A shell command's output depends on machine state; a file edit mutates a workspace the replay may not have. The replayable core of a session is its API/MCP surface: data pulls, status checks, report generation, CRUD sequences. A session with none of that gets an honest empty result, with every skipped call named.

## Related

- [Deterministic replay — what a compiled skill does when you run it](https://www.reelier.com/learn/deterministic-replay)
- [MCP recording — the wrap-proxy capture path when there is no history to scan](https://www.reelier.com/learn/mcp-recording)
- [Write gating — why compiled-from-session skills replay read-only by default](https://www.reelier.com/learn/idempotent-write-gating)
- [Set it up on Claude Code — scan your history, freeze a session, replay it](https://www.reelier.com/for/claude-code)
- [From the blog: record once, replay the part that never changes](https://www.reelier.com/blog/scheduled-agents-zero-token)

## Sources

- [MindStudio — What Is the Session-to-Skill Extractor? (the LLM-review family, and the term's origin)](https://www.mindstudio.ai/blog/session-to-skill-extractor-agent-procedures)
- [Anthropic — Equipping agents for the real world with Agent Skills (the SKILL.md artifact)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [seldonframe/reelier — the open-source (AGPL-3.0) deterministic compiler this page describes](https://github.com/seldonframe/reelier)

Other terms: [Deterministic replay](https://www.reelier.com/learn/deterministic-replay) · [Agent drift](https://www.reelier.com/learn/tool-call-drift) · [Run receipt](https://www.reelier.com/learn/run-receipt) · [Level-0 (zero-token) replay](https://www.reelier.com/learn/level-0-replay) · [Snapshot testing for AI agents](https://www.reelier.com/learn/agent-snapshot-testing) · [Recording MCP tool calls](https://www.reelier.com/learn/mcp-recording) · [Regression testing for AI agents](https://www.reelier.com/learn/agent-regression-testing) · [Idempotent write gating](https://www.reelier.com/learn/idempotent-write-gating) · [Assertion grammar for agent outputs](https://www.reelier.com/learn/assertion-grammar) · [Agent memory vs deterministic replay](https://www.reelier.com/learn/agent-memory-vs-replay) · [Headless agent](https://www.reelier.com/learn/headless-agent)