# Reelier vs LLM-executed agent skills (SKILL.md)

> An agent SKILL.md and a Reelier skill are the same file format with two runtimes: the agent skill is instructions a model reads and follows at its discretion each run, while a Reelier skill is a recording a deterministic executor re-runs identically with an assertion on every step it can check.

Markdown twin of https://www.reelier.com/vs/reelier-vs-agent-skills — an honest comparison of LLM-executed agent skills and Reelier. It leads with where LLM-executed agent skills genuinely wins, then draws the line where Reelier fits. The blockquote above is the one-sentence distinction; quote it with the link.

## Where LLM-executed agent skills win

Reach for an agent skill when the value of the task is in the model reasoning about it every single run. An Anthropic Agent Skill is a directory with a `SKILL.md`: YAML frontmatter (`name`, `description`) that Anthropic's docs call discovery metadata loaded into the system prompt, and a markdown body of instructions the model reads only once the description matches your request. At run time the model uses that skill — in Anthropic's words, "automatically when relevant" — deciding whether to trigger it, which of its files to open, and how to adapt its steps to the situation in front of it. That flexibility is the whole point.

Because a model executes the skill, novelty is handled for free. A new input shape, an error the recording never saw, a step that should be skipped or reordered because the world moved since you wrote it — the model absorbs all of that in its forward pass. Progressive disclosure lets one skill compose large reference files and bundled scripts without paying for them until they're needed, and the docs are explicit that skills mix "instructions for flexible guidance" with code for the reliable parts. The fuzzy front of a task — deciding *what* to do, triaging, synthesizing, writing — is exactly where a frozen recording is silent and a model is essential.

So if your job's worth is its judgment, an agent skill is the right runtime and Reelier is the wrong one. Nothing below argues otherwise. Agent skills are structured guidance by design; they raise consistency without pretending to be deterministic automation, and treating "the model might do this step differently next time" as a bug would be misreading what the tool is for.

## Where Reelier fits

The same flexibility that makes a skill great for judgment is a liability for the parts that must be byte-identical every run. Because the model decides whether and how to follow the instructions, a step can be skipped, reordered, or done a little differently — fine for prose, not fine for "always pull this metric, always in this order, always check the field came back." Reelier gives that half of the same `SKILL.md` a second runtime: a deterministic one.

You record a real run — `reelier from-session` from your agent history, or `reelier mcp --wrap` for a fresh capture — and `reelier compile` turns the recorded tool calls into steps with typed arguments and an assertion on every step it can check. The honesty is in that last clause: a step whose recording returned a clean result gets an assertion (`status == 200`, plus a `json.<path> is set` for any value a later step consumes); a step that failed or returned nothing during recording stays assertion-less and is listed as an open question, never quietly marked passed. Then `reelier run` re-executes exactly those calls at 0 LLM tokens and writes a receipt, and from the second run on `reelier diff` exits 1 when a real response drifts.

This isn't Reelier versus your skill — the two runtimes share the file on purpose. `reelier compile --from-skill <SKILL.md>` reads your agent skill's own frontmatter and carries its `name` and `description` into the compiled deterministic skill, while every step still comes only from the recorded trace — Reelier never generates a step from instruction text, because a guessed step replayed deterministically would be a lie with a receipt. Keep the model-run skill to decide what to do and to handle everything novel; compile the deterministic half into a Reelier skill that locks it down and hands you proof.

The trade-offs stay honest and narrow. Replay only covers what re-executes deterministically — MCP tool calls and Reelier's `http.get`/`http.post` builtins — so an edit-heavy or judgment-heavy skill compiles to little or nothing, and Reelier says so instead of inventing steps. Replay is read-only by default: `--allow-writes` unlocks idempotent writes only, and a destructive step still refuses without `--yes`. Judgment, when a replay needs it, stays opt-in and BYOK, in levels, and a destructive step is never auto-escalated. What you buy is a run whose every checkable step is verified the same way each time, at zero model cost — the guarantee the model runtime, by design, doesn't make.

## Side by side

| | LLM-executed agent skills | Reelier |
| --- | --- | --- |
| The file | A `SKILL.md` directory: YAML frontmatter (`name`/`description`) + a markdown instructions body | The same `SKILL.md` format, compiled: steps with typed args + an assertion on each checkable step |
| What runs it | A model, each run — reads the instructions, decides whether and how to follow them | A deterministic executor — `reelier run` re-executes the recorded tool calls |
| Determinism | Flexible and non-deterministic by design — a step may be skipped, reordered, or adapted | Same calls, same order, every run — drift fails an assertion, `reelier diff` exits 1 |
| Novelty / unseen inputs | Handled — the model adapts in its forward pass | Not handled — a frozen recording can't; that's an honest limit, not a feature |
| Cost per run | Model tokens every run (the instructions re-enter context when triggered) | 0 LLM tokens, measured on the receipt |
| Verification | The model's own judgment — no deterministic per-step pass/fail receipt | An assertion per checkable step; a receipt in `.reelier/runs/` every run |
| Sharing the file | Authored as guidance the model discovers via its `description` | `reelier compile --from-skill` carries that name/description; steps come only from a recorded trace |

## A real receipt

The output below is a real replay receipt, not a mockup — and the thing being run is literally a `.skill.md` file. The `registry-latest` portfolio skill (`examples/portfolio/registry-latest.skill.md`) is the same file format an agent would read as guidance; here Reelier's deterministic runtime executes it, checks the recorded step's assertion against the live npm registry, and stamps a passed, timed receipt. Replayed on 2026-07-21 with the CLI pinned to the version that recorded the seed (`npx -y reelier@0.12.1`), so it reproduces verbatim.

```
npx -y reelier@0.12.1 run examples/portfolio/registry-latest.skill.md

=== registry-latest ===
✓ Step 1 — Latest dist-tag from the registry [passed] 152ms

PASSED: 1/1 steps ok, 0 failed, 152ms total
```

Verbatim seed receipt from seldonframe/reelier examples/portfolio/README.md (reelier@0.12.1, 2026-07-21). The run record confirms passed: true and 0 LLM tokens. Replay it yourself from a checkout of the repo — read-only, no account, no key.

## Related

- [Skill compilation — how a recorded session becomes a deterministic SKILL.md](https://www.reelier.com/learn/skill-compilation)
- [Deterministic replay — what the second runtime does when it runs the file](https://www.reelier.com/learn/deterministic-replay)
- [Sibling comparison — recording a run vs hand-writing the script](https://www.reelier.com/vs/reelier-vs-hand-written-scripts)
- [Set it up on Claude Code — scan your history, freeze a run, replay it](https://www.reelier.com/for/claude-code)

## Sources

- [Anthropic — Agent Skills overview (SKILL.md directory, name/description frontmatter, progressive disclosure, "used automatically when relevant")](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Anthropic Engineering — Equipping agents with Agent Skills (the model loads and uses skills at its discretion)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [seldonframe/reelier — the open-source (AGPL-3.0) engine: compile, --from-skill, and the deterministic runner this page describes](https://github.com/seldonframe/reelier)

Other comparisons: [VCR / Polly.js](https://www.reelier.com/vs/reelier-vs-vcr) · [promptfoo](https://www.reelier.com/vs/reelier-vs-promptfoo) · [LangSmith](https://www.reelier.com/vs/reelier-vs-langsmith) · [Temporal](https://www.reelier.com/vs/reelier-vs-temporal) · [Codex Record & Replay](https://www.reelier.com/vs/reelier-vs-codex-record-replay) · [Muscle-Mem](https://www.reelier.com/vs/reelier-vs-behavior-caches) · [a hand-written script](https://www.reelier.com/vs/reelier-vs-hand-written-scripts)