This playbook is for a lead who wants to build a shared skill library their team will actually use. It covers the setup, the initial seeding, the conventions that keep the library coherent, and the lightweight habits that make reuse stick.
A skill library only works if people contribute to it and reach for it. Both behaviors need a small amount of scaffolding to become defaults.
Step 1: Get everyone’s sessions captured
A skill library built from real work requires real work to be captured. Before you can seed the library, every engineer on the team needs to be running their agent work through paperctl — whichever agent they use.
Have each engineer:
- Install and authenticate
paperctlif they have not already — see the quickstart. - Start agent sessions through paper instead of invoking the agent directly.
- Confirm the sessions land:
paperctl sessions listshows the run at the top of the list.
The start command has the same shape for every supported agent:
paperctl start claudepaperctl start codexpaperctl start piA mixed team is fine — sessions from every agent land in the same library. Tools like Conductor can route through paper as well, and Codex has a few authentication paths worth checking before rollout.
As the lead, verify the rollout from the same terminal: paperctl sessions list returns your whole organization’s recent sessions, so teammates’ runs appear alongside your own — --auth-subject <user-id> scopes the list to one person when you want to check on a specific teammate. If someone’s sessions are missing, they are likely not routing through paperctl yet.
Want to check your team’s sessions in the console instead? The Sessions list in the team workspace shows the same data with a Scope toggle for switching between your runs and the whole team’s.
Step 2: Seed the library with your strongest sessions
Once you have a week or two of captured sessions, you have raw material to work with. Start the library with three to five skills drawn from your team’s most experienced engineers’ sessions — the sessions that solved real problems cleanly.
What to look for when picking sessions to extract:
- Sessions that navigated a non-obvious tool sequence and reached a clean outcome.
- Sessions that resolved a class of error your team encounters more than once.
- Sessions that set up or migrated something your team will do again.
- Sessions from engineers who know the codebase well — their tool choices and decision paths tend to produce better skills than sessions from someone still learning the environment.
What to skip:
- One-off explorations with no repeatable procedure.
- Sessions that succeeded by working around a problem rather than solving it.
- Sessions that are too short to have meaningful signal.
For each candidate, generate a skill from the terminal — semantic search finds the session, one command extracts it:
paperctl search "the work you remember solving" -k 3
paperctl skill generate <session-id> --name 'Descriptive Skill Name'Turn sessions into skills from the CLI walks this loop end to end, including generating one skill from several sessions. If you prefer the UI, open the session in paper console and choose Generate Skill instead — both paths land the skill in the same org library, immediately visible to the whole team.
Add your skill, and encourage the team to add skills that fill a knowledge gap for the whole team — the setup only one person has done, the fix only one person knows. Every session like that left unextracted is valuable knowledge capture the team loses.
Use search to find the skills your team needs
The strongest skill candidates are often invisible to any one engineer, because the signal is spread across the team: three people quietly solving the same problem in three separate sessions. paperctl search spans your whole organization’s captured sessions, so one query surfaces that repetition.
paperctl search "configure a new service against the staging identity provider" -k 10When the hits cluster — the same class of work appearing across multiple sessions, especially sessions that are not your own — you have found a skill the team needs. Repetition across engineers means the problem recurs, the solutions have already been paid for, and everyone is maintaining their own private variation of the answer.
Often the signal shows up in conversation before anyone thinks to look for it: someone mentions in standup that they fought the deploy check you fixed last week, or a retro reveals that three people have each “figured out” the migration runbook. That conversation is the search query. Run it, pick the sessions that solved the problem cleanly, and generate one skill from the set — paperctl skill generate accepts multiple session ids, so the skill draws on the whole spread instead of one person’s take:
paperctl search "how we ran the schema migration" -k 10
paperctl skill generate <session-id-1> <session-id-2> --name 'Run a Schema Migration'Then close the loop: tell the team the skill exists and that it is the way this task gets done from now on — one announcement in the channel where the repetition surfaced, and a sync command away for everyone. One reviewed skill replacing several private variations is the payoff of the whole system: the team standardizes on the best version, the friction of re-solving disappears, and everyone moves faster.
Step 3: Establish naming and tagging conventions
A skill library becomes hard to use when skills have inconsistent names or no tags. Set conventions early, before the library grows.
Naming: Use names that describe what the skill does, not who made it or when. Prefer action-oriented names that answer “what will this help me do?” — for example, “Debug flaky integration tests” or “Scaffold a new service”. Avoid names tied to your current tooling version unless the version is the point.
Tags: Pick a small set of tags your team will actually use and stick to them. Useful tag categories include:
- Task type (debugging, scaffolding, migration, review)
- Environment or stack (e.g., the platform or runtime your team uses)
- Target component or area (e.g., “auth”, “infra”, “api”)
Descriptions: One or two sentences that answer “when would I reach for this?” — not a summary of what was in the session.
Contributing: Generating a skill publishes it to the team library immediately — there is no draft state. Generate from sessions worth sharing, and review the result right away so teammates never sync a skill that still carries session-specific context.
Step 4: Establish a lightweight review convention
Generating a skill publishes it — the moment it is created it is in the library, visible to the team, and syncable. Review cannot gate what enters the library, so it has to follow fast: a lightweight after-generation review is what keeps the library worth trusting.
Who reviews: For a small team, the lead or a rotating reviewer is enough. The goal is one set of eyes on each newly generated skill, soon after it lands.
What to check in review:
- The trigger accurately describes when to use the skill in general terms — not tied to one session’s exact context.
- The steps are generalizable. Session-specific paths, project names, and environment details have been replaced with placeholders.
- No credentials, API keys, or sensitive paths are in the content.
- The name and tags match your conventions.
- The description answers “when would I reach for this?” clearly.
Generated means published: There is no draft or review state to park a skill in. What makes this safe is versioning — each version is an immutable snapshot (v0.1.0, v0.2.0, and so on), and updating a skill publishes a new one while older versions stay browsable. When review turns something up, fix it by editing the skill and publishing the updated version; if the skill should not have been generated at all, remove it from the Skills view in paper console.
Changelogs: When you publish a new version of an existing skill, write a brief changelog entry that says what changed and why. “Updated tool sequence for new API response shape” is enough. Older versions stay browsable, so the changelog gives context when someone compares versions.
Step 5: Make reuse a habit
A library that exists but no one consults is not useful. Two habits make the difference:
Before starting a recurring task, check the library. Make this the default for the team: before an engineer runs a session for a task the team has done before, they should check whether a skill exists. From the terminal, that is one command:
paperctl skill list --query <keyword>Or use the Skills view in paper console with the scope filter set to your team, searching by task type or tag.
After a session that solved something hard, ask “is this a skill?” Make this a normal part of post-session review: if the session solved a real problem and the approach is repeatable, run paperctl skill generate on it — or open it in paper console and choose Generate Skill. The library grows because individuals notice value and capture it — not because a process forces them to.
When a teammate installs a skill: sync writes the skill’s SKILL.md straight into the agent’s skills directory:
paperctl skill sync <slug> --claudepaperctl skill sync <slug>Install a Skill covers per-project installs and updating when a new version is published. (You can also download the SKILL.md from the skill’s page in paper console and place the file yourself.) This is the moment the library earns its value — the skill captures how a problem was solved once so no one has to rediscover it.
Keeping the library healthy
A library grows most useful when it is also maintained. A few practices that help:
Retire or update skills when the environment changes. An API response shape changes, a tool is replaced, a service moves. Skills that describe the old environment will lead agents astray. Treat skill maintenance as part of the normal change process — when something your skills depend on changes, update the skill and publish a new version.
Prune skills that are never used. If a skill has never been downloaded and has been sitting unchanged since it was published, it is probably not solving a real problem for anyone. Remove it or mark it as a candidate for replacement with something more targeted.
Revisit the seed skills after a few months. The skills you published first were based on limited session history. After your team has run more sessions, go back to the early skills and check whether newer sessions have produced better procedures worth incorporating.