Agent Registry

# Agent Registry

Lazy-loading system for Claude Code agents. Eliminates the "~16k tokens" warning by loading agents on-demand.

## CRITICAL RULE

**NEVER assume agents are pre-loaded.** Always use this registry to discover and load agents.

## Workflow

``` User Request → search_agents(intent) → select best match → get_agent(name) → execute with agent ```

## Available Commands

| Command | When to Use | Example | |---------|-------------|---------| | `list.js` | User asks "what agents do I have" or needs overview | `bun bin/list.js` | | `search.js` | Find agents matching user intent (ALWAYS do this first) | `bun bin/search.js "code review security"` | | `search-paged.js` | Paged search for large registries (300+ agents) | `bun bin/search-paged.js "query" --page 1 --page-size 10` | | `get.js` | Load a specific agent's full instructions | `bun bin/get.js code-reviewer` |

## Search First Pattern

1. **Extract intent keywords** from user request 2. **Run search**: `bun bin/search.js "<keywords>"` 3. **Review results**: Check relevance scores (0.0-1.0) 4. **Load if needed**: `bun bin/get.js <agent-name>` 5. **Execute**: Follow the loaded agent's instructions

## Example

User: "Can you review my authentication code for security issues?"

```bash # Step 1: Search for relevant agents bun bin/search.js "code review security authentication"

# Output: # Found 2 matching agents: # 1. security-auditor (score: 0.89) - Analyzes code for security vulnerabilities # 2. code-reviewer (score: 0.71) - General code review and best practices

# Step 2: Load the best match bun bin/get.js security-auditor

# Step 3: Follow loaded agent instructions for the task ```

## Installation

### Step 1: Install the Skill

**Quick Install (Recommended):**

```bash # Using Skills CLI (recommended) npx skills add MaTriXy/Agent-Registry@agent-registry

# Discover skills interactively npx skills find

# Update existing skills npx skills update ```

**Traditional Install:**

```bash # User-level installation ./install.sh

# OR project-level installation ./install.sh --project

# Optional: install enhanced interactive UI dependency ./install.sh --install-deps ```

**What install.sh does:** 1. Copies skill files to `~/.claude/skills/agent-registry/` 2. Creates empty registry structure 3. Optionally installs dependencies via `--install-deps` (`@clack/prompts` for enhanced UI)

### Step 2: Migrate Your Agents

Run the interactive migration script:

```bash cd ~/.claude/skills/agent-registry bun bin/init.js # Optional destructive mode: bun bin/init.js --move ```

**Interactive selection modes:**

- **With @clack/prompts** (default): Beautiful checkbox UI with category grouping, token indicators, and paging - Arrow keys navigate, Space toggle, Enter confirm - Visual indicators: [green] <1k tokens, [yellow] 1-3k, [red] >3k - Grouped by subdirectory

- **Fallback**: Text-based number input - Enter comma-separated numbers (e.g., `1,3,5`) - Type `all` to migrate everything

**What init.js does:** 1. Scans `~/.claude/agents/` and `.claude/agents/` for agent files 2. Displays available agents with metadata 3. Lets you interactively select which to migrate 4. Copies selected agents to the registry by default (`--move` is explicit opt-in) 5. Builds search index (`registry.json`)

## Dependencies

- **Bun** (ships with Claude Code) — zero additional dependencies for core functionality - **@clack/prompts**: Optional enhanced interactive selection UI (install via `./install.sh --install-deps`)

## Registry Location

- **Global**: `~/.claude/skills/agent-registry/` - **Project**: `.claude/skills/agent-registry/` (optional override)

Agents not migrated remain in their original locations and load normally (contributing to token overhead).