Use Cases · skill

cat ./why-and-when.md

When you reach for skill_pool.

Six concrete scenarios, drawn from how teams actually adopt this tool. Each section explains the why (pressure they felt), the when (signals it's time), and the how (which features matter most).

Scenario 1 — The 15-engineer startup

Who: Series A SaaS, three product squads, two infra engineers, six months of Claude Code adoption.

Why they hit a wall. Every engineer's ~/.claude/skills/ looks different. The senior on the billing team wrote a brilliant stripe-webhook-debug.md — only Sarah uses it. The infra lead's terraform-drift-check.md ships in his dotfiles repo, which nobody else clones. Onboarding a hire means asking them to "grab the awesome-claude-list and pick what looks good," which is code for start from zero again.

When the signal arrives.

Someone in a retro says: "we should have a place for these prompts."
A second team is duplicating a skill the first team already wrote.
Onboarding doc has a section that ends in "...and ask in #eng-tooling."

How they roll it out (week 1).

# Day 1 — infra deploys it
$ kubectl apply -f deploy/helm/skill-pool
OK skill-pool reachable at skills.acme.internal

# Day 2 — curate per-repo bundles
$ cd acme-billing-service
$ skill-pool project init --pin code-reviewer,stripe-webhook-debug,sqlx-migrations
$ git commit .skill-pool/manifest.toml

# Day 3 — engineers see it on next clone
$ git clone git@github.com:acme/billing-service && cd billing-service
$ direnv allow
OK bootstrapped 6 skills · 2 agents from skill-pool

What's load-bearing here: Projects (per-repo bundles), auto-bootstrap, semantic search to discover what exists.

Scenario 2 — Multi-tenant SaaS platform

Who: A vendor whose customers are themselves engineering teams. Each customer's engineers want their own Claude Code skill registry, branded as their own.

Why this is hard otherwise. Per-customer hand-rolled deploys are how SaaS dies. You either run one giant pile that leaks customer A's skills into customer B's catalog, or you run N copies and your on-call sees N times the alerts.

When this fits.

You want a single shared cluster for cost & ops simplicity.
You want regulated customers to opt into dedicated isolation without rewriting the app.
Customers expect their own logo, domain, SSO. "skill-pool.acme.com", not "acme.skill-pool.io".

How it's wired.

Shared mode — every row carries tenant_id; routes resolve from subdomain or custom domain (Caddy + ACME automation). Every sqlx::query! is statically verified to filter by tenant_id — see Invariant #1.
Per-tenant theme — logo, palette, font, favicon, custom domain. Stored in tenant_themes; sanitized server-side.
SSO — OIDC or SAML 2.0 per tenant, SCIM provisioning, scoped API tokens (read-only / publish / admin).
Audit log — every mutation writes an immutable row; export to SIEM via signed JSONL.

The dedicated escape hatch. When a customer signs a contract with "no shared infrastructure" clauses, you don't fork the app — you run the same image with a different DATABASE_URL and STORAGE_URL. Same Helm chart, same deploy pipeline.

Scenario 3 — Regulated enterprise (SOC 2 / FedRAMP / GxP)

Who: Internal platform team at a regulated F500. AI tooling has to clear security before engineers can use it.

What security/compliance asks for.

"Where do skills come from? Can someone publish a prompt that exfiltrates an API key?" → secret scan on every publish. Server-side regex sweep rejects bundles that look like they ship credentials.
"Who can publish? Who can install? Who reviewed it?" → RBAC + audit log. Every publish, delete, approve, login, token mint writes an audit row.
"Can we export this to our SIEM?" → signed JSONL export per tenant, with retention policy.
"What if Claude itself goes down? Do we lose the catalog?" → no. skill-pool is self-hosted; skills live in your Postgres + object storage. Claude is just one consumer.

Dedicated-mode tenant layout.

acme-prod      → DB: skills_prod      bucket: s3://acme-skills-prod      domain: skills.acme.com
acme-gov       → DB: skills_gov       bucket: s3://acme-skills-gov-fr    domain: skills-gov.acme.com  (FedRAMP)
acme-research  → DB: skills_research  bucket: s3://acme-skills-research  domain: skills-rd.acme.com

Same binary, three deployments, isolated blast radius. Cost is N × baseline — which is the point: you trade efficiency for isolation.

Scenario 4 — Consultancy / agency

Who: A 40-person dev agency with 12 active client engagements. Each client's tech stack is different. Each client has their own quirks the team learns over months.

The pain. Consultants rotate. When Maria leaves the Globex engagement, the next consultant onboards from a wiki page that hasn't been updated since the kickoff three quarters ago. Maria's .claude/ went with her laptop.

How skill_pool changes it.

One server, one tenant per client. Each client has their own logo & SSO if the contract requires it.
Projects are per-repo bundles — globex-payments-service pins exactly the skills that matter for it.
Retrospective capture turns Maria's actual debugging sessions into draft skills. When she rotates off, her replacement gets the same skills, automatically.
Decay flags stale skills (last_used > 6mo ∧ uses < 3) — the catalog stays trim as engagements end.

Scenario 5 — OSS maintainer publishing a plugin

Who: Maintainer of an OSS framework. Wants to ship a Claude Code plugin so users of the framework get expert help out of the box.

The flow.

# Maintainer publishes a plugin (skills + agents + slash commands + hook)
$ skill-pool publish ./my-framework-claude-plugin --kind plugin --version 2.1.0
  packing: 18 skills · 3 agents · 4 commands · 1 hook (245 KB)
  OK plugin published · marketplace entry generated
       https://skills.public.example/.claude-plugin/marketplace.json

# A user installs it in Claude Code
User: /plugin marketplace add https://skills.public.example
User: /plugin install my-framework-toolkit
  OK 18 skills · 3 agents installed in ~/.claude/plugins/my-framework-toolkit

The maintainer doesn't run a marketplace by hand. marketplace.json is generated server-side from the plugin row; the smart-HTTP git endpoint is what /plugin install clones.

Scenario 6 — Capturing tribal knowledge automatically

Who: Any team where engineers solve real problems in Claude Code daily, but nobody has time to write them up afterward.

The pipeline.

A Stop-hook on the developer's machine scores the session deterministically — token count, time on task, edit density, test-run ratio. "This looks like a real fix."
A SessionEnd-hook queues the transcript to ~/.skill-pool/capture-queue/.
A capturer daemon runs Haiku → extracts topic, tags, intent. Then runs Sonnet → drafts the SKILL.md.
The draft lands in the curator's drafts inbox on the portal. Diff against existing skills, edit, approve, publish.

Why this works in practice. The expensive step (writing it up) gets done by the model, on a sample of sessions the scorer flagged as worth bothering with. Humans stay in the loop where their judgment actually matters: is this a skill we want the whole team to have?

The catalog grows from work that already happened, not from someone's bookmark folder.

When NOT to use this

Be honest with yourself. skill_pool is overkill for some shapes of team:

Solo developer. Just commit your ~/.claude/ to dotfiles. You don't need a registry.
Two-person team where you share an editor. Pair-sharing is faster than infra.
You haven't adopted Claude Code yet. Start there. Come back when "everyone's .claude/ is different" feels real.
You don't have a platform team and don't want one. Self-hosting Postgres + object storage + a Rust server has a floor of operational complexity. The hosted SKILL.md hubs (when they exist) will fit you better.

The rule of thumb. If the answer to "where do you keep your team's prompts?" is "in the awesome-list / in Notion / in someone's dotfiles", and the answer to "who decides what's good?" is "whoever Slacks loudest," that's the moment you need this. Before that, it's premature.

$ try it locally → watch the onboarding demo