How long does a session need to be to produce a useful skill?

There is no minimum length, but a session that only touches one or two turns rarely has enough signal. Look for a session where the agent worked through a real problem — multiple turns, meaningful tool calls, a clear outcome. Thin sessions produce thin skills.

What if the generated draft is too specific to my local paths or environment?

That is expected. The generation step lifts everything from the session, including local context you do not want to ship. Review the draft and replace any project-specific paths, credentials, or environment details with generic placeholders before publishing.

Can I generate more than one skill from the same session?

Yes. If a session covered more than one distinct workflow, open it again and run Generate Skill a second time with a different hint focused on the other part of the session.

SKILL.md is the file that paper console generates and stores for each skill. It contains the trigger, procedure, decision points, and any other structured guidance extracted from the session. Drop it into a project directory so your agent can reference it.

What is the difference between saving a draft and publishing?

Saving keeps the skill in an editable draft state — it is visible to you but not finalized. Publishing creates an immutable versioned snapshot (v1, v2, and so on) with a changelog entry. Teammates searching the Skills view will find published versions; drafts stay yours until you are ready.

Publish your first skill - Paper Compute Docs

This walkthrough takes you from a fresh paper CLI session to a published skill available for your whole team in paper console. The process has six steps and takes about fifteen minutes the first time.

Capture a session worth extracting

Run your agent work through the paper CLI so the session is captured:

paper start claude

Then use Claude Code normally. paper CLI captures the session in the background — prompts, tool calls, turns, cost, duration, and completion status.

If you already have sessions captured in paper console, move to the next step.

Identify the right session

Open paper console and go to the Sessions view. You are looking for a session that:

Solved a real problem — not a trial run or a quick lookup, but a task that required multiple steps and produced a useful result.
Completed cleanly — the session reached a successful outcome without unrecoverable errors partway through.
Contains a repeatable workflow — the steps the agent took would apply again the next time someone faces the same situation.
Belongs to a task you or a teammate will face again — debugging a specific deployment environment, scaffolding a particular project type, triaging a recurring class of error.

Open the session to review its chain and tool calls before generating a skill. If the session is sparse — a handful of turns and no meaningful tool calls — pick a richer one.

Generate the skill

From the session detail page in paper console, choose Generate Skill.

You can optionally provide a short hint to seed the draft:

Name — what you want to call this skill.
Description — what it does in one sentence.
Type — the kind of skill (e.g., debugging, scaffolding, migration).
Tags — terms that will help teammates find it later.

You do not have to fill all of these in — the hint just guides the extraction. Leave fields blank if you are not sure yet; you can fill them in during review.

paper console extracts a draft SKILL.md from the session’s prompts, tool calls, and turns.

Review and edit the draft

The generated draft is a starting point. Before publishing, open the editor and work through each part:

Trigger — does it describe when this skill applies in general terms, not just for your specific task? Tighten it if the extraction copied too much session context.

Steps — which steps were specific to your session (your local paths, your project name, your test environment) and which are genuinely reusable? Replace session-specific details with generic placeholders.

Secrets and paths — scan for any credentials, API keys, file paths, usernames, or environment-specific values. Remove or replace them before publishing. The generated draft will not always catch these.

Decision points and error handling — does the draft capture what happened when things went wrong or required a choice? If a key decision was implicit in the session, make it explicit in the skill.

Name and description — revise them to describe the general workflow, not the specific instance you ran.

Tags and type — add tags a teammate would search for. Think about what problem they would be trying to solve when this skill is useful.

Visibility — decide whether to keep the skill private to yourself or share it with your team. You can change this before or after publishing.

Saving at this point keeps the skill as a draft. Take your time; a draft can sit until you are satisfied.

Publish v1

When the draft reads well and you have scrubbed session-specific context, publish it.

Publishing creates an immutable v1 with a changelog entry. The skill is now in the Skills view for anyone with access to find it. You can continue editing — future publishes will create v2, v3, and so on — and older versions stay browsable.

Download SKILL.md and use it

To use the skill in a project, open it in paper console and download its SKILL.md.

Drop the file into your project directory. Your agent can reference it when starting related work — either by loading it directly or by following the procedure it describes.

You can also share the skill URL with teammates so they can download SKILL.md into their own projects.

If the draft is weak

Not every session produces a good first draft. Common reasons and what to do:

The session was too thin. A short session with few tool calls gives the extraction step almost nothing to work with. Go back, run the real task fully through paper start claude, and generate from that richer session instead.

The steps are too session-specific. If the draft reads like a transcript of your exact run rather than a generalizable procedure, edit it. Replace the specific with the general: your project name becomes <project-name>, your local path becomes <path-to-project>, your specific error message becomes a description of the error class.

The trigger is wrong or missing. The trigger tells the agent when to reach for the skill. If it is missing or describes only your exact scenario, rewrite it to describe the general situation — task type, environment, error pattern — that makes this skill relevant.

The draft includes multiple unrelated workflows. If the session covered more than one task, the extraction may have blended them. Edit down to the single most useful workflow, or generate a second skill from the same session with a different hint.

The skill duplicates an existing one. Before publishing, search the Skills view. If a skill already covers the same ground, consider whether you have something genuinely new — a better procedure, an updated environment, a cleaner approach — or whether the existing skill needs a new version instead.