Freeze an AI Agent Session into a Doppels Capability

The freeze workflow is built around a simple idea: do real work first, then capture it. You open your agent — Claude, Cursor, Codex, or any other supported tool — and work through the problem the normal way. You deploy, migrate, scrape, transform, whatever needs doing. When you have something that works, you say the freeze phrase and the doppel-freeze skill takes over. It reads your session, writes a Capability and Recipe in YAML, validates them with the CLI, and asks for your sign-off. From that point forward, the same operation runs locally for zero tokens, every time.

doppel freeze is a skill for AI agents — not a CLI subcommand. There is no doppels freeze command in the binary. The agent writes the YAML; the CLI validates and runs it.

Step 1: Install the freeze skill

Install the skill once per machine or per project. It registers itself with your agent environment so that any supported agent can pick it up.

npx skills add doppelshq/doppels --skill doppel-freeze

This works with all supported agents:

Claude
Cursor
Codex
OpenCode
Windsurf
VS Code

You only need to do this once. After installation, every agent session on that machine has access to the freeze skill.

You also need the doppels CLI on your PATH. If you haven’t installed it yet, see the installation guide.

Step 2: Do real work in your agent

Open a session in your agent of choice and work through the task you want to capture. There is nothing special to do at this stage — write code, run commands, call APIs, fix the migration, whatever the job is. The freeze skill will read the session history, so the more concrete and complete the work, the better the resulting Capability. Good candidates for freezing include:

Fetching data from an API and writing it to a file
Running a database migration
Building and packaging a release artifact
Rotating credentials or applying configuration changes
Generating a report from raw data

Step 3: Say the freeze phrase

When the work is done and you’re satisfied with the result, tell your agent to freeze it. Use natural language — something like:

“doppel freeze — turn what we just did into a Capability”

“doppel freeze this as hn-top-stories”

The agent recognizes the doppel freeze trigger and activates the skill. You don’t need to use an exact incantation; the skill is designed to recognize intent.

What the freeze skill does

Once triggered, the skill works through a fixed sequence without requiring further prompting from you:

Check for the doppels CLI

The skill verifies that doppels is available on your PATH. If it isn’t, it tells you exactly how to install it before proceeding.

Initialize the Space if needed

If the current folder doesn’t have a .doppels/ directory yet, the skill runs doppels spaces init to create the standard layout: capabilities/, recipes/, and .doppels/.

Identify what to capture

The skill asks you to confirm what outcome to capture. Each distinct outcome becomes one Capability. If the session produced multiple separable results, you can freeze them individually.

Write the YAML by hand

The agent reads through the session — commands run, files written, inputs received, outputs produced — and writes capabilities/<name>.yaml and recipes/<name>.yaml directly. There is no code generator or doppels freeze command doing this work; the agent is authoring the YAML.

Validate and test

The skill loops doppels validate and a test doppels run until the manifests are clean and the Capability executes correctly. It fixes any schema errors or expression problems it finds.

Ask for your sign-off

The skill shows you the full contract — inputs, outputs, steps — and waits for your approval before treating the Capability as done.

Step 4: Review and commit the YAML

After the skill finishes, you’ll have two new files in your project:

capabilities/<name>.yaml — the public contract (inputs and outputs)
recipes/<name>.yaml — how it runs (steps, shell commands, return values)

Open them in your editor and review the diff. Check that the inputs match what you actually provided, that the steps reflect what happened in the session, and that the outputs capture what you care about. Then commit both files to Git like any other source file.

git add capabilities/hn-top-stories.yaml recipes/hn-top-stories.yaml
git commit -m "freeze: hn-top-stories v1.0.0"

Sample frozen YAML

Here is what a frozen Capability and Recipe look like for a Hacker News story fetcher — the kind of task you might build in a single agent session and want to replay indefinitely. capabilities/hn-top-stories.yaml

apiVersion: doppels.so/v1alpha1
kind: Capability

metadata:
  name: hn-top-stories
  version: 1.0.0
  displayName: Fetch Top Hacker News Stories

inputs:
  limit:
    type: integer
    required: false

outputs:
  stories_csv:
    type: artifact
    mediaType: text/csv
  story_count:
    type: integer

recipes/hn-top-stories.yaml

apiVersion: doppels.so/v1alpha1
kind: Recipe

metadata:
  name: hn-top-stories
  version: 1.0.0

provides: [hn-top-stories]
runtime: shell

requires:
  commands: [curl, python3]

defaults:
  approval: never

steps:
  - id: fetch
    name: Fetch top story IDs
    env:
      LIMIT: "{{ inputs.limit }}"
    run:
      shell: sh
      script: |
        LIMIT="${LIMIT:-10}"
        curl -sf "https://hacker-news.firebaseio.com/v0/topstories.json" \
          | python3 -c "import sys,json; ids=json.load(sys.stdin)[:int('$LIMIT')]; print('\n'.join(map(str,ids)))" \
          > story_ids.txt

  - id: write_csv
    name: Fetch stories and write CSV
    run:
      shell: sh
      script: |
        echo "id,title,score,url" > stories.csv
        while IFS= read -r id; do
          python3 -c "
import urllib.request, json, csv, sys
data = json.loads(urllib.request.urlopen(
  'https://hacker-news.firebaseio.com/v0/item/$id.json').read())
w = csv.writer(sys.stdout)
w.writerow([data.get('id',''), data.get('title',''), data.get('score',''), data.get('url','')])
" >> stories.csv
        done < story_ids.txt
        export STORY_COUNT=$(tail -n +2 stories.csv | wc -l | tr -d ' ')
    produces:
      stories_csv:
        file: stories.csv
      story_count:
        env: STORY_COUNT

returns:
  stories_csv: "{{ steps.write_csv.stories_csv }}"
  story_count: "{{ steps.write_csv.story_count }}"

You can freeze any repeatable operation: data pipelines, API integrations, web scraping, report generation, data transforms, DevOps tasks, and more. If you did it once with an agent and it worked, it’s a good candidate for a Capability.

Get Started

Core Concepts

Guides

Agent Skills

Reference

Freeze an AI Agent Session into a Doppels Capability

Step 1: Install the freeze skill

Step 2: Do real work in your agent

Step 3: Say the freeze phrase

What the freeze skill does

Step 4: Review and commit the YAML

Sample frozen YAML

​Step 1: Install the freeze skill

​Step 2: Do real work in your agent

​Step 3: Say the freeze phrase

​What the freeze skill does

​Step 4: Review and commit the YAML

​Sample frozen YAML

Step 1: Install the freeze skill

Step 2: Do real work in your agent

Step 3: Say the freeze phrase

What the freeze skill does

Step 4: Review and commit the YAML

Sample frozen YAML