> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doppels.so/llms.txt
> Use this file to discover all available pages before exploring further.
# doppel-freeze: Freeze Agent Sessions into YAML Recipes
> The doppel-freeze skill teaches your agent to capture any working session into a versioned, typed Capability and Recipe you can replay locally forever.
`doppel-freeze` is an agent skill — a set of instructions loaded into Claude, Cursor, Codex, OpenCode, Windsurf, VS Code, or any other compatible agent. Once installed, you trigger it by asking your agent to freeze what you just accomplished. The agent reads the session context, authors the YAML manifests by hand, validates them against the Doppels schemas, and presents the finished contract for your review. The result is a committed, deterministic Capability and Recipe your entire team can replay with zero tokens.
There is no `doppels freeze` CLI command. Freeze is performed entirely by the agent skill — the agent writes the YAML. The CLI provides `doppels validate` and `doppels run` to verify and execute the resulting manifests.
## Install the skill
Run the install command once per machine or project. After that, every supported agent in that environment gains freeze capabilities.
```shell theme={null}
npx skills add doppelshq/doppels --skill doppel-freeze
```
To target a specific agent instead of all configured agents, pass the `-a` flag:
```shell Claude theme={null}
npx skills add doppelshq/doppels -a claude-code
```
```shell Cursor theme={null}
npx skills add doppelshq/doppels -a cursor
```
```shell Codex theme={null}
npx skills add doppelshq/doppels -a codex
```
## Trigger a freeze
After completing any repeatable task in your agent session, ask your agent to freeze it. You can phrase the request naturally:
> "doppel freeze — turn what we just did into a Capability"
> "doppel freeze this as deploy-to-staging"
> "freeze the migration we just ran as a reusable Capability"
The agent recognises the intent and begins the freeze workflow immediately.
## What the skill does
The skill verifies that `doppels` is installed and accessible. If it isn't, the agent shows you the install instructions before proceeding.
If your project has no `.doppels/` directory yet, the agent runs `doppels spaces init` to create `capabilities/`, `recipes/`, and `.doppels/` in the current working directory.
The agent asks you what to freeze. Each distinct outcome becomes its own Capability — one Capability per thing the session accomplished.
The agent inspects the full session: every command run, file touched, input provided, and output produced. Nothing is inferred — only what actually happened is captured.
The agent writes `capabilities/.yaml` and, where appropriate, `recipes/.yaml` by hand. There is no generator command — the agent authors the YAML directly based on the session.
The agent loops `doppels validate` and runs `doppels run …` (when it is safe to do so) until every manifest is clean and the output matches what the session produced.
The agent shows you the finished Capability and Recipe and waits for your confirmation before treating the freeze as complete.
Once you confirm, the agent asks you to commit the YAML to your repository. The committed file is the repeatable asset — anyone with it can run the same Capability on their machine.
## Example: freezing a CSV export
Suppose you just had your agent build a script that fetches the top Hacker News stories and writes them to a CSV. After confirming it works, you say:
> "doppel freeze this as hn-top-stories"
The agent produces two files:
```yaml capabilities/hn-top-stories.yaml theme={null}
name: hn-top-stories
version: 1.0.0
description: Fetch the top Hacker News stories and write them to a CSV file.
inputs:
- name: limit
type: integer
description: Number of stories to fetch.
default: 30
outputs:
- name: stories_csv
type: file
description: CSV file containing the fetched stories.
```
```yaml recipes/hn-top-stories.yaml theme={null}
name: hn-top-stories
provides: capability/hn-top-stories
version: 1.0.0
steps:
- name: fetch-stories
uses: http.get
with:
url: "https://hacker-news.firebaseio.com/v0/topstories.json"
- name: fetch-details
run: node scripts/fetch-details.js
with:
limit: "{{ inputs.limit }}"
- name: write-csv
run: node scripts/write-csv.js
returns:
- name: stories_csv
path: ./stories.csv
```
Anyone who clones your repository can now run:
```shell theme={null}
doppels run capability/hn-top-stories --input limit=50 --yes
```
## Use cases
`doppel-freeze` is useful for any repeatable task you currently re-explain to your agent from scratch. Common examples include:
* 🗄️ **Data pipelines** — ETL flows, scheduled ingestion, transformation chains
* 🔌 **API integrations** — authenticated fetches, webhook handlers, sync jobs
* 🕸️ **Web scraping** — structured extraction with pagination and retry logic
* 📊 **Report generation** — templated outputs from live data sources
* 🔀 **Data transforms** — reshaping, filtering, enriching datasets
* 🛠️ **DevOps tasks** — deploys, rollbacks, environment setup scripts
* 🗃️ **Database migrations** — schema changes, seed scripts, backups
* 🚀 **Build & release scripts** — version bumps, changelog generation, publish flows
## After the freeze
Once the YAML is committed to your repository, it becomes a permanent, shareable asset:
* **Anyone on your team** can run the same Capability with `doppels run` — no agent required, zero tokens consumed.
* **Every run** produces an auditable log under `.doppels/runs//` with full step-by-step output.
* **Credentials stay local** — Doppels inherits your host auth (`aws`, `gcloud`, `psql`, SSH, VPN). Nothing is sent to the cloud.
Run `doppels validate` immediately after the freeze completes and before you commit. A clean validation confirms the schema is correct and the manifests are ready to replay.
```shell theme={null}
doppels validate
```