agent-registry

---
name: agent-registry
version: 2.0.1
description: |
  MANDATORY agent discovery system for token-efficient agent loading. Claude MUST use this skill
  instead of loading agents directly from ~/.claude/agents/ or .claude/agents/. Provides lazy
  loading via search and get tools. Use when: (1) user task may benefit from
  specialized agent expertise, (2) user asks about available agents, (3) starting complex
  workflows that historically used agents. This skill reduces context window usage by ~95%
  compared to loading all agents upfront.
hooks:
  UserPromptSubmit:
    - hooks:
        - type: command
          command: "bun ${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_search.js"
          timeout: 5
---

# 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 rele