How to Build a Team Skill Library From Real AI Usage

Building a team skill library from actual AI usage starts with a different question than the one most teams ask. Instead of “what should our agents know how to do?”, the right question is “what have our agents already done successfully?”

The difference sounds subtle. It is not. The first question produces a wishlist of imagined skills, authored from memory and intuition. The second produces a library grounded in evidence — skills extracted from sessions that worked, with the actual procedures, decision paths, and error fixes intact instead of reconstructed from memory a week later.

This page covers how to share successful AI coding workflows across a team when you build the library from real usage data rather than from scratch.

Why prompt libraries and hand-authored skills decay

Teams writing skills from scratch are making a bet: that the author’s mental model of what works is accurate enough to be useful to someone else running a different session under different conditions.

Sometimes it is. Often it is not, and in a specific way. Skills written from memory tend to have happy paths but not the error branches that matter. They capture the imagined procedure, not the actual one — which means they miss the step you only discovered because you hit the failure. And they age: as tooling, APIs, and infrastructure change, a skill that lives as a text file someone authored once drifts silently from reality.

A 2026 study of knowledge transfer in software teams found that what gets lost in handoff is not the high-level architecture — people document that. What gets lost is the Decision Shadow: the constraints, rejected alternatives, and failure paths that shaped the decision but never made it into the artifact. Skills written from memory have the same shadow. The troubleshooting path is the thing you forgot to write down.

The alternative is not to write more carefully from memory. It is to change the starting point: your team’s actual sessions.

Stage one: get consistent capture running

A skill library built from real usage requires real usage to draw from. That means sessions need to be captured as they run, by everyone on the team, consistently.

Run paperctl start claude before each Claude Code session:

paperctl start claude

The same wrapper covers the other agents a team runs — paperctl start codex, paperctl start pi — and mixed teams are fine: every captured session lands in the same library regardless of which agent produced it.

paperctl routes the session through a proxy that records the provider traffic — the prompts, the responses, and the tool calls and errors that pass through them — without changing how engineers work. The boundary matters: work that never reaches the provider is not part of the record. What is captured is the decision trail the model actually saw and produced, which is exactly the material a skill is extracted from.

This step has no immediate payoff. The payoff is downstream. Every captured session is a candidate for pattern extraction. Every uncaptured session is institutional knowledge that evaporates when the terminal closes.

Across a team, the arithmetic compounds: every engineer’s daily sessions are a steady stream of extraction candidates. Most teams keep none of it. The teams that capture, accumulate.

Stage two: find what your best engineers are actually doing

The question “how do I capture what my best engineer does with AI and teach it to the whole team?” has a specific answer: you look at their sessions.

A senior engineer who consistently gets Claude Code to solve a class of problem effectively is following a procedure — whether or not they could articulate it. The session record has the procedure. The task is identifying which sessions are worth extracting from.

The patterns with the highest team value tend to be:

• The recurring setup your team does more than once. Service onboarding, authentication configuration, telemetry wiring. The first successful session is the template. Extract it before the second person reinvents it.
• The debugging session where someone found the actual root cause. Not the session where someone worked around the symptom — the one where the failure mode was correctly identified and fixed. That fix path is the skill.
• The session where a less experienced engineer got unstuck by pairing with someone senior. The senior engineer’s prompting strategy, the way they structured context, the order they called tools — these are patterns. A skill is how you make the pattern available without requiring the senior engineer to be present.
• Anything a new engineer will ask about in their first two weeks. Onboarding tasks are the first place a skill library shows its value. New engineers inherit the team’s solved problems instead of rediscovering each one.

Stage three: extract, review, and refine for the team

Once a session is identified as worth sharing, skill extraction converts it from a transcript into a structured skill.

Extraction runs from either surface. From the terminal, paperctl skill generate <session-id> turns a captured session into a skill without leaving the shell — paperctl search finds the session first. In paper console, open the session and choose Generate Skill. Either path produces the same thing: a typed artifact with a trigger, procedure, decision branches, and troubleshooting drawn from what the session actually did — not what someone remembers it doing — published to the team library the moment it is generated.

Generated does not mean finished. The skill is live in the library immediately, so review is a fast follow rather than a gate — someone reads what was generated and checks:

1. Does the trigger generalize? A trigger scoped too narrowly will only fire on the exact conditions from one session. Widen it to cover the class of task, not the specific run.
2. Does the procedure hold up? Read the steps. The session may have succeeded for an incidental reason that does not generalize. The review step is how you catch over-fitted procedures before they propagate to the team.
3. Is the scope right? Skills should say when they apply and when they do not. A skill for a specific infrastructure pattern should be explicit about that scope so it does not misfire on different setups.

When review turns something up, edit the skill and publish the updated version — versions are immutable, so corrections are explicit and older versions stay browsable. Teams that prefer version control can also keep skills as files in a shared skills directory in a repository. Either way, the skill is available to every engineer running a session — one paperctl skill sync away from any agent’s skills directory. The skill that one person extracted from a Tuesday debugging session is the procedure everyone can invoke on Wednesday.

The docs cover the operational version of this loop: turn sessions into skills from the CLI for the terminal path, and roll out a team skill library for the team-wide playbook.

What a team skill library built from real usage enables

Three things change when you build a skill library from actual usage rather than from prompts written from scratch.

1. Onboarding compresses. A new engineer can search the library for the procedures they need instead of asking a teammate or starting from zero. The library is what the team has already figured out, available directly.
2. The strongest engineer’s patterns scale. When your best engineer finds a better approach to a class of task, that approach does not stay in their session history. It becomes a skill the whole team applies. The capability is no longer gated on one person’s availability.
3. The library improves rather than decaying. Skills built from session evidence can be updated with new evidence. A skill whose infrastructure assumptions change gets refreshed from a new session, not abandoned. The library compounds instead of going stale.

The governance layer

A skill library only works if the team trusts it. Because generation publishes immediately, trust requires that what lands in the library gets reviewed quickly — a habit that follows generation, not a gate in front of it. One bad skill that fires incorrectly on a real task creates more skepticism about the library than five good skills create confidence.

Treat the shared library like a shared codebase: changes go through review, versions are explicit, and someone is responsible for the quality of what lands in it. Skills can live in a repository directory and be reviewed through normal pull requests. The same tooling that governs your code governs the library.

The review habit is what keeps signal-to-noise ratio high enough that engineers keep reaching for the library instead of skipping it — the foundation of team-shared agent knowledge.

Where to start

The first skill in a team library is almost always extracted from a session that already happened — something a teammate resolved a month ago that keeps coming up. Find that session with paperctl search or in paper console, run extraction, and review what lands in the library.

That one skill is the existence proof that the library works. The sessions keep running. The library keeps growing.

Start with paperctl start claude running for everyone, consistently. The skills come from the sessions. The sessions are already happening.