Quickstart

Five deploy paths. Pick the surface that fits your platform team — same image, same migrations, same CLI.

Nix flake — recommended for hacking

$ git clone https://github.com/olafkfreund/skill_pool && cd skill_pool
$ nix develop                                   # drops you in the dev shell
$ docker compose -f server/compose.yaml up -d   # Postgres + MinIO + Caddy
$ cargo run --bin skill-pool-server             # API on :8080
$ cd web && npm install && npm run dev          # portal on :3000

Open http://localhost:3000. Want it pre-populated with 120+ skills?

$ ./scripts/seed-demo.sh

Docker Compose — no Nix required

$ docker compose -f server/compose.yaml up -d
# API:    http://localhost:8080
# Portal: http://localhost:3000
# Caddy:  http://localhost:8081  (subdomain-routed tenants)
# MinIO:  http://localhost:9001  (console)

NixOS module — for declarative homelab + prod

# flake.nix
{
  inputs.skill-pool.url = "github:olafkfreund/skill_pool";

  outputs = { self, nixpkgs, skill-pool, ... }: {
    nixosConfigurations.skills-host = nixpkgs.lib.nixosSystem {
      modules = [
        skill-pool.nixosModules.default
        ({ ... }: {
          services.skill-pool = {
            enable = true;
            tenants = [ "acme" "internal" ];
            settings.STORAGE_URL = "s3://skills-bucket?endpoint=...";
            settings.DATABASE_URL_FILE = "/run/agenix/skill-pool-db.url";
          };
        })
      ];
    };
  };
}

Full module docs: docs/deploy/nixos.md. The module composes systemd hardening (NoNewPrivileges, ProtectSystem, DynamicUser) and reads secrets from *_FILE paths so it plays cleanly with agenix or sops-nix.

Helm chart — Kubernetes

$ helm repo add skill-pool https://olafkfreund.github.io/skill_pool/charts
$ helm install skills skill-pool/skill-pool \
    --set postgres.dsn=postgres://… \
    --set storage.url=s3://skills?endpoint=… \
    --set ingress.hosts[0].host=skills.acme.com \
    --namespace skills --create-namespace

The chart at deploy/helm/skill-pool/ includes a job runner for migrations, HPA, PodDisruptionBudget, NetworkPolicy, and an optional Redis subchart.

Terraform AWS — opinionated production stack

# deploy/terraform/aws/example/main.tf
module "skill_pool" {
  source = "github.com/olafkfreund/skill_pool//deploy/terraform/aws"

  cluster_name       = "skills-prod"
  region             = "eu-west-1"
  domain             = "skills.acme.com"
  certificate_arn    = aws_acm_certificate.skills.arn
  github_oidc_org    = "acme"
  github_oidc_repo   = "infrastructure"

  rds_instance_class = "db.t4g.large"
  redis_node_type    = "cache.t4g.micro"
}

Provisions EKS · RDS Postgres · ElastiCache Redis · S3 bucket · ACM cert · IRSA role for the pod · GitHub OIDC trust so CI can deploy without long-lived AWS keys.

First CLI session

$ cargo install --path cli            # or: nix profile install .#cli
$ skill-pool login                    # interactive OIDC or token paste
$ skill-pool detect --json
{"stack": ["rust", "axum", "postgres", "nixos"]}

$ skill-pool search "axum middleware"
SLUG                  VERSION  USED   DESCRIPTION
axum-middleware       1.4.0    87×    layer pattern, error mapping, tracing
axum-tower-trace      0.2.1    14×    request-scoped span + structured logging

$ skill-pool add axum-middleware
OK linked ~/.skill-pool/library/acme/axum-middleware@1.4.0 → ~/.claude/skills/

$ skill-pool doctor
OK registry reachable
OK token valid · tenant: acme
OK 1 skill linked into .claude/skills/
OK no dangling symlinks

Per-repo projects

A project is a curator-pinned bundle of skills/agents/commands, addressed by the repo's git remote URL. Commit it to the repo.

$ cd acme-billing-service
$ skill-pool project init
# writes .skill-pool/manifest.toml

$ skill-pool project pin code-reviewer@1.2.0 sqlx-migrations@2.0.1 cs-backend-engineer@0.9.0
$ git add .skill-pool/ && git commit -m "chore: pin claude skills"

# Anyone who clones this repo gets the same bundle:
$ git clone git@github.com:acme/billing-service && cd billing-service
$ skill-pool ensure
OK installed 3 skills from .skill-pool/manifest.toml

Auto-bootstrap with direnv

Drop one .envrc line. direnv allow on first cd detects your stack and prompts to install matching skills.

# .envrc (one-time install: skill-pool direnv-install)
use skill-pool

$ direnv allow
detected: rust, axum, postgres, nixos
install 4 matching skills? [Y/n] _
OK installed 4 skills · linked into .claude/skills/

Seed with 120+ real skills

$ ./scripts/seed-demo.sh
seeding 76 skills · 43 agents · 1 command · tenant theme · members · drafts · SSO config · usage events
OK portal populated · login as admin@acme.test

Demo content from borghei/Claude-Skills (MIT + Commons Clause, attribution preserved). Useful for screenshotting, demos, and stress-testing the lifecycle pipeline.

$ author a plugin → api reference