Definition
Turning a Claude Code session into a reusable skill is a two-part workflow: capture the session as it runs (paperctl start claude), then extract the reusable pattern — trigger, procedure, decisions, troubleshooting, scope — from what the session actually did, review it, and store it as a versioned skill future runs can invoke.
Turning Claude Code sessions into reusable skills follows a specific workflow: capture the session as it runs, then extract the reusable pattern from what it actually did. Skip the capture step and extraction is impossible. Run both and each session that resolves a real problem becomes a permanent asset instead of a transcript that disappears when the terminal closes.
paperctl start claude
(proxy records provider traffic — prompts · responses
· tool calls and errors that pass through them)
│
▼
Recorded session
│
▼
Worth extracting?
recurring setup · known fix · repeated migration
· non-obvious tool sequence
│
▼
paper console: Generate Skill → draft
│
▼
Review: does it generalize? is it causally correct?
│
▼
Skill library (published · versioned · team-visible)
│
▼
Future run matches the trigger → skill invokedWhat a Claude Code session contains that is worth keeping
When Claude Code solves a real problem — debugging a pipeline failure, wiring up a service integration for the first time, migrating a data schema across multiple repos — it follows a specific path. It calls tools in a specific order. It hits errors and routes around them. It makes decisions based on what the tools return. That decision trail — the exchange between the agent and the model — is in the session record.
That trail is a procedure. When the same class of problem comes up again — same infrastructure pattern, similar error signature, same kind of task — an agent that can consult the procedure skips the parts you already figured out. An agent that cannot has to rediscover them from scratch. That is the loop continuous agent improvement describes: the step between keeping the record and making it work for you.
The session that solved the problem already contains the reusable procedure. The question is whether you kept it.
Creating skills from real Claude Code sessions starts here: the information you need is already in the session. The workflow is about keeping it.
Step one: capture before the session starts
You cannot extract a skill from a session you did not keep. Capture has to run before the session starts.
Launch Claude Code through paperctl instead of directly:
paperctl start claudeThe paperctl CLI routes the session through a local proxy that records the provider traffic as it happens: every prompt, every model response, and the tool calls and errors that pass through them. That is the decision sequence as the model saw it, not a summary written afterward. The boundary matters: activity that never enters provider traffic — a tool failure handled locally and never reported back to the model, for example — does not appear in the session record.
Proceed with Claude Code as normal. Capture is transparent. You do not change how you work; you just have something real to work with when the session ends.
Step two: identify what is worth extracting
Not every session needs to become a skill. Most sessions are exploratory or one-off. The ones worth extracting share two properties: they solved a real problem, and the solution generalizes beyond the specifics of that one run.
Patterns worth turning into skills tend to be:
- Recurring setups. Any service integration you configure more than once across projects. The first session that gets it right is the one to extract from.
- Error paths with known fixes. A session that hit a specific error, diagnosed it correctly, and applied a fix that worked. The troubleshooting path is the value — especially the edge cases not in the docs.
- Multi-step migrations or refactors that follow the same pattern across codebases. Once you have done it twice, the pattern is real.
- Tool sequences that are not obvious. The right order of calls for a non-obvious task, the specific flags that matter, the configuration that actually works versus the one that looks right in the docs but does not.
A practical signal: if you would have to explain it to a new engineer next time, it is a candidate for a skill.
Step three: generate and review the draft
In paper console, open the recorded session and choose Generate Skill. The console runs skill extraction over the session record and returns a draft skill: a structured artifact with a type (workflow, prompt template, or domain knowledge), a trigger that describes when the skill applies, the tool sequence extracted from the session, decision branches the agent navigated, and error signatures with their fixes.
The draft is not a finished skill. Review it before publishing. Two things to verify:
- Does it generalize? A skill that only fires on the exact file paths and variable names from one run is not useful. The trigger should cover similar future tasks, not just the specific session it came from.
- Is the procedure causally correct? The session produced the right outcome — but is the extracted procedure accurately capturing why? Read the steps. A session can succeed for an incidental reason, and extracting that reason bakes in a pattern that does not hold on the next run.
Edit the draft in the console, then publish it. It is now a versioned skill in your skill library.
What a good extracted skill looks like
A skill extracted from a Claude Code session has five components:
| Trigger | The task type or error signature that activates it. "Setting up Confluent Cloud topic producers for the first time" is a specific, useful trigger. "Python environment issue" is too broad to be actionable. |
|---|---|
| Procedure | The ordered steps, stripped of run-specific literals but keeping the generalized form. References env variable names rather than actual values, function patterns rather than one-time function names. |
| Decision points | The branches the session navigated based on observed state. "If the topic does not exist, create it manually before retrying the producer." Real decisions from real runs, not hypothetical branches you imagined. |
| Troubleshooting | Error signatures the session actually hit, with root cause and fix. The value is the edge cases: the failure mode that is not in the official docs but that you found the hard way. |
| Scope | When the skill applies and when it does not. A skill built for one specific infrastructure should say so, so it does not fire silently on a different setup. |
Step four: store it where future runs can find it
A reviewed skill belongs in a versioned location. In paper console, a skill is either published or it is not. Publishing creates an immutable version (v1, v2, and so on) that is visible to everyone on your team, so publish once you are confident in the steps.
Skills can also be checked into a project repository as files, which adds code review and diffability on top of the console’s version history. Either way: versioned and reviewable so that changes are deliberate and a previous version can be restored if a skill drifts.
When a future session starts a task that matches the trigger, the skill is available as context. The agent applies the procedure without rediscovering it. That is skill invocation — the runtime step where a stored skill reaches a live run.
The return compounds
The first skill you extract is worth one problem solved. The value comes from what it prevents: the second time that class of problem appears, nobody re-derives the fix from scratch. By the time a team has ten reviewed skills covering its common recurring tasks, the aggregate time saved across sessions is real.
Each session is a candidate. Each extraction is a deposit into a library that pays out on every future run that matches. The library does not stay static — as new sessions produce new evidence, skills get updated with better troubleshooting, sharper triggers, and corrected assumptions.
Start with paperctl start claude running before your next session. The procedure you extract from it is the one you would have written from memory a week from now, except it will be complete.