Skip to content

Designing the Library

A skill library is not a pile of skills you can grep. It's a curated set, and the thing being curated is scarce: every skill you load injects its description into the agent's system prompt on every single request, whether or not it fires. The library's real budget is context, not disk. Design it like you're spending everyone's attention, because you are.

Context economics: the shared tier taxes everyone

Here's the asymmetry that drives every design decision. A skill in the shared, loaded-by-default set costs its description's worth of context to every user's agent, on every turn — even the users who will never trigger it. Ten marginal shared skills is a permanent tax on an entire organization's context window, paid whether or not anyone benefits. So the bar for "load this for everyone" is much higher than the bar for "this skill is useful." Useful-to-some and worth-loading-for-all are different questions, and conflating them is how libraries bloat.

There's a second, subtler cost: discovery degrades as the set grows. Every loaded description is another candidate the agent weighs when deciding what to trigger, so a bloated default set doesn't just spend tokens — it makes the agent worse at picking the right skill, because the signal for any one skill is diluted by dozens of near-misses. Fewer, sharper skills trigger more reliably than many overlapping ones. That's why a design decision to keep a skill out of the default set is often a quality decision, not just a budget one.

Three tiers, one promotion path

The workshop library uses three tiers that trade off reach against review cost:

  • Personal (users/{username}/skills/) — no review, visible only to you. Where you prototype.
  • Team (teams/{team}/skills/) — team review, discoverable by others, loaded by team members who opt in. Where a skill hardens.
  • Shared (skills/) — platform review plus an eval gate, loaded by default for everyone. The narrowest, most expensive tier.

These form a deliberate progression: prototype personal, harden in team, promote to shared only when a skill is broadly, cross-functionally useful. A team-specific skill in the shared directory isn't a convenience — it's the context tax above, levied on everyone in the organization who'll never use it.

Configs and inheritance

What a given agent actually loads is decided by config, and configs compose by inheritance rather than duplication. A personal config names your own picks and inherits a team collection, which in turn draws from the shared set:

// user-example.json — your picks, plus everything the team config resolves to
{
  "entries": [{ "path": "users/dewi/skills/my_experimental_skill" }],
  "inherits": [{ "path": "configs/team-example.json" }]
}

Inheritance means a team improves its collection once and every member's agent picks it up — no per-person edits, no drift between copies. It's the same "single source of truth" logic that made references one level deep back in Module 02, applied to library composition. It also means installation is what makes triggering possible in the first place: a skill the config never resolves to is simply invisible to the agent, no matter how good its description. So the config is not an afterthought — it's the other half of discovery. A great skill that nobody's config loads has exactly the same effect as no skill at all.

Curate the default set aggressively

Because the shared set is the expensive one, curation there is subtractive. The team config below pulls only two specific skills from another team and takes the shared set minus one it doesn't want — rather than inheriting everything and hoping:

// team-example.json — include_only and exclude keep the set tight
{
  "entries": [
    { "path": "teams/payments/skills", "include_only": ["reconciliation", "chargeback_review"] },
    { "path": "skills", "exclude": ["partner_api"] }
  ]
}

Contrast the disciplined org-defaults.json, which loads just three broadly-useful skills — incident_triage, sql_analytics, partner_api — with the tempting anti-pattern of adding every team's favorite to the default set "so it's there if needed." The first spends context deliberately; the second spends everyone's context on everyone's maybes. When in doubt, leave it out of the default and let teams opt in.

This is also where the tier hierarchy pays off as a workflow, not just a taxonomy. A skill earns its way up: it proves itself useful to one person in the personal tier, hardens under team review where a smaller group actually relies on it, and reaches the shared default set only after it has demonstrated broad value and passed the eval gate. Each promotion widens the blast radius and raises the review bar to match. Designing the library well is mostly designing this gradient — making it easy to prototype low and deliberately hard to land in the set everyone pays for.

Key takeaways

  • The library's scarce resource is context, not storage: every loaded skill's description is a standing cost on every request.
  • Three tiers trade reach for review rigor; promote to shared only for broad, cross-functional value, not mere usefulness.
  • Configs compose by inheritance, so a collection is maintained once and inherited many times — curate the default set subtractively.

Drill it

  • ex08_design_the_library — set the tiers, curate the org-default set, and work through a context-economics worksheet using these configs.

(Exercises unlock in the Exercises section; direct links are wired as each one lands.)