The Library

A unified catalog of skills, agents, commands, and scripts across all repos.

What It Does

Scans ~15 source repos, discovers ~309 artifacts by convention (SKILL.md, AGENT.md, .md commands, executable scripts), and produces a single generated/catalog.yaml. A thin SKILL.md wrapper provides /library list, /library search, and /library scan commands in Claude Code.

Quick Start

# Clone
git clone git@github.com:UXCXNZ/the-library.git ~/Code/tools/the-library
cd ~/Code/tools/the-library

# Install deps
pnpm install

# Build the catalog (scans all repos on disk)
pnpm build

# Symlink into Claude Code
ln -s ~/Code/tools/the-library ~/.claude/skills/library

Commands

Command	What it does
/library list	Show all artifacts (filterable by type, scope, consumer, profile)
/library search <query>	Full-text search across names, descriptions, aliases
/library scan	Validate catalog against disk (read-only)

Filters

/library list --type skill
/library list --scope shared --consumer claude-code
/library list --profile content
/library search convex

Adding a New Source Repo

1. Edit config/sources.yaml with the repo, branch, local paths, and scan rules
2. Run pnpm build
3. Commit the updated generated/catalog.yaml

Adding Overrides and Profiles

Edit config/overrides.yaml to add descriptions, owners, aliases, or profiles. Rebuild to apply.

Architecture

sources.yaml + overrides.yaml
         |
    build-catalog.ts (walks repos on disk)
         |
    generated/catalog.yaml (committed, deterministic)
         |
    SKILL.md (list, search, scan)

• config/sources.yaml: repo roots and scan rules (human-maintained)
• config/overrides.yaml: descriptions, owners, aliases, profiles (human-maintained)
• generated/catalog.yaml: every artifact found (machine-generated, committed)
• scripts/build-catalog.ts: produces the catalog
• scripts/check-catalog.ts: validates catalog against disk
• phase2/: parked cookbooks for installation/sync/push (not yet implemented)
• docs/v1-catalog.md: Phase 1 design rationale
• docs/v2-distribution.md: Phase 2 prospective

Artifact Types

Type	Discovered by	Count
skill	Directory with SKILL.md	~250
agent	Directory with AGENT.md	~17
command	.md file	~26
script	Executable file	~16

What's NOT in Phase 1

No installation, sync, push, or load management. The catalog is read-only. To change it, edit config and rebuild. See docs/v2-distribution.md for the Phase 2 roadmap.