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 skill 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 skill 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 does publishing a skill do?

A skill is either published or not. Publishing creates an immutable versioned snapshot (v1, v2, and so on) with a changelog entry, and a published skill is visible to everyone on your team in the Skills view. Later publishes create new versions, and older versions stay browsable.

Publish your first skill - Paper Compute Docs

This walkthrough takes you from a fresh paperctl 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 paperctl CLI so the session is captured:

paperctl start claude

Then use Claude Code normally. (Codex and Pi capture the same way: paperctl start codex or paperctl start pi.) paperctl 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 generation:

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 first SKILL.md from the session’s prompts, tool calls, and turns.

Review and edit the skill

The generated skill 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. Generation will not always catch these.

Decision points and error handling — does the skill 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.

Take your time working through the skill — nothing is visible to your team until you publish.

Publish v1

When the skill 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, visible to everyone on your team. You can continue editing — future publishes will create v2, v3, and so on — and older versions stay browsable.

Install it and use it

To use the skill in a project, install it:

paperctl skill sync <slug> --claude

Sync writes the SKILL.md where your agent reads it (--claude targets Claude Code’s skills directory; --local scopes it to the current project). You can also open the skill in paper console and download its SKILL.md yourself. Share the skill’s slug or URL with teammates so they can install it the same way.

If the generated skill is weak

Not every session produces a good first cut. 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 paperctl start claude, and generate from that richer session instead.

The steps are too session-specific. If the skill 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 skill 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.