Turn captured sessions into skills

A session where the agent got something right is a pattern worth keeping. Tapes extracts that pattern from the derived transcript with an LLM, stores it under ~/.tapes/skills/, and installs it into agent skill directories. The transcript follows the main conversation spine — harness shadow calls such as permission checks and title generation are excluded.

Before you start

A running server with at least one captured session:

tapes local up
tapes serve

Read commands default to the read API on http://localhost:8081; a server elsewhere is tapesctl config set api-url <url> once.

Generation calls an LLM, so it needs a provider key — see the table below.

Generate

A name in kebab-case is required:

tapesctl skill generate <session-id> --name debug-react-hooks

The <session-id> is the tapes session id from tapesctl sessions list — not the harness id start prints on exit. Pass several ids for a skill drawn from more than one session, or skip the ids and let span search pick them:

tapesctl skill generate --search "gum glow charm" \
  --search-top 3 --name charm-cli-patterns

Two servers are involved and they are not the same one: --api-url addresses the read API that supplies the transcript, while --provider and --model address the LLM that does the extraction.

Provider	Default model	Key read from	Key required
openai (default)	gpt-4o-mini	OPENAI_API_KEY	yes
anthropic	claude-haiku-4-5-20251001	ANTHROPIC_API_KEY	yes
ollama	llama3.2	either, if set	no

Prefer the environment variable over --api-key: a key passed on the command line is visible in the process list and in shell history for as long as the command runs.

Add --preview to see the transcript and prompt before anything is generated, and --type to pick between workflow, domain-knowledge, and prompt-template.

Review what you have

tapesctl skill list
tapesctl skill list --type workflow

Generated skills are files you can inspect and version like other agent instructions. Read one before installing it — a session captured in one project can carry that project’s assumptions.

Install into an agent

Installing is a local file copy with no server involved. By default, sync writes to the global, agent-neutral ~/.agents/skills/:

tapesctl skill sync debug-react-hooks

Choose project-local or Claude Code paths explicitly:

tapesctl skill sync debug-react-hooks --local             # .agents/skills/
tapesctl skill sync debug-react-hooks --claude            # ~/.claude/skills/
tapesctl skill sync debug-react-hooks --claude --local    # .claude/skills/
tapesctl skill sync debug-react-hooks --dry-run

Use --dry-run first when the source session contained project-specific assumptions.

Next steps

• Search captured sessions by meaning — find the sessions worth extracting; --quiet output pipes straight into generate.
• Skills reference — every flag, including date filters.