---
name: library
description: Unified catalog of skills, agents, commands, and scripts across all repos. Use when the user wants to list, search, or scan their library of artifacts. Triggers on /library commands.
argument-hint: [list|search|scan] [filters or query]
---

# The Library

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

## Variables

- **LIBRARY_DIR**: `~/.claude/skills/library/`
- **CATALOG_PATH**: `~/.claude/skills/library/generated/catalog.yaml`

## Commands

| Command | What it does |
|---|---|
| `/library list [--type X] [--scope X] [--consumer X] [--profile X]` | Display filtered catalog |
| `/library search <query>` | Case-insensitive search across names, descriptions, aliases |
| `/library scan` | Validate catalog against disk, report errors and warnings |

## Cookbook

Each command has a detailed step-by-step guide. **Read the relevant cookbook file before executing a command.**

| Command | Cookbook |
|---|---|
| list | [cookbook/list.md](cookbook/list.md) |
| search | [cookbook/search.md](cookbook/search.md) |

## How It Works

The catalog is a generated YAML file (`generated/catalog.yaml`) built from `config/sources.yaml` by running `pnpm build` in the library directory. It scans repo roots on disk for skills (SKILL.md), agents (AGENT.md), commands (.md files), and scripts (executables).

**The catalog is read-only at runtime.** To add or change entries, edit `config/sources.yaml` or `config/overrides.yaml` and rebuild.

### Scan command

`/library scan` runs `check-catalog.ts` which validates the committed catalog against local disk. It reports:
- Missing artifacts (cataloged but not on disk)
- Uncataloged artifacts (on disk but not in catalog)
- Duplicate names across repos
- Branch mismatches
- Broken profile references

It never writes. To rebuild, run `pnpm build` in `<LIBRARY_DIR>`.

### Artifact Types

| Type | Discovered by | Name source |
|---|---|---|
| `skill` | Directory containing `SKILL.md` | Frontmatter `name` field, fallback to directory name |
| `agent` | Directory containing `AGENT.md` | Frontmatter `name` field, fallback to directory name |
| `command` | `.md` file under scan path | Filename without extension |
| `script` | Executable file under scan path | Filename without extension |

### Canonical ID Format

`{repo_slug}:{artifact_type}:{name}`

Example: `orion-agents-and-skills:skill:story-coach`

### Profiles

Profiles group related artifacts for a workflow. Defined in `config/overrides.yaml`. Filter with `--profile`.