Roll out a team skill library

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 the paper CLI.

Have each engineer:

1. Install and authenticate the paper CLI if they have not already — see the quickstart.
2. Start agent sessions with paper start claude instead of invoking the agent directly.
3. Check that their sessions appear in the paper console Sessions view under your team’s org.

Use the Scope toggle in the Sessions view to confirm you can see your teammates’ runs alongside your own. If someone’s sessions are missing, they are likely not routing through the paper CLI yet.

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 session: open it in paper console, choose Generate Skill, and follow the review process. See Publish your first skill for the full review checklist.

Aim for three to five well-edited, published skills before telling the rest of the team the library is open. A library with no entries or only draft entries does not give teammates a reason to look.

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.

Visibility: The convention that matters most is that anything load-bearing is team-visible. Engineers can keep private skills for personal workflows they are still refining, but once a skill is something teammates should use, set its visibility to team before publishing.

Step 4: Establish a lightweight review and publish convention

Skills that go straight from generation to publish without review accumulate noise. A lightweight review step filters out low-quality drafts and 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 the draft before it becomes a published version.

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.

Drafts vs published versions: Drafts are the right home for skills in progress. A skill sits as a draft while it is being reviewed or refined. Publishing creates an immutable versioned snapshot (v1, v2, and so on) with a changelog entry. Reserve publishing for skills you are confident are ready — teammates will rely on published versions.

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 Skills view. Make this the default for the team: before an engineer runs a session for a task the team has done before, they should search the Skills view first. Use the scope filter set to your team, search by task type or keyword, and check whether a skill exists before running from scratch.

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, open it in paper console and generate a skill. The library grows because individuals notice value and capture it — not because a process forces them to.

When a teammate downloads a skill: To use a skill, open it in paper console, download its SKILL.md, and drop it into the relevant project. The agent can reference it when starting related work. 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.