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_agents.py	User asks "what agents do I have" or needs overview	python scripts/list_agents.py
search_agents.py	Find agents matching user intent (ALWAYS do this first)	python scripts/search_agents.py "code review security"
search_agents_paged.py	Paged search for large registries (300+ agents)	python scripts/search_agents_paged.py "query" --page 1 --page-size 10
get_agent.py	Load a specific agent's full instructions	python scripts/get_agent.py code-reviewer

Search First Pattern

Extract intent keywords from user request

Run search: python scripts/search_agents.py ""

Review results: Check relevance scores (0.0-1.0)

Load if needed: python scripts/get_agent.py

Execute: Follow the loaded agent's instructions

Example

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

# Step 1: Search for relevant agents
python scripts/search_agents.py "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
python scripts/get_agent.py security-auditor

# Step 3: Follow loaded agent instructions for the task

Installation

Step 1: Install the Skill

Quick Install (Recommended):

# NPX with add-skill (recommended)
npx add-skill MaTriXy/Agent-Registry

# OR npm directly
npm install -g @claude-code/agent-registry

Traditional Install:

# User-level installation
./install.sh

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

What install.sh does:

✓ Copies skill files to ~/.claude/skills/agent-registry/

✓ Creates empty registry structure

✓ Automatically installs questionary Python package (for interactive UI)

✓ Falls back gracefully if pip3 not available

Note: All installation methods support Python-based migration and CLI tools

Step 2: Migrate Your Agents

Run the interactive migration script:

cd ~/.claude/skills/agent-registry
python scripts/init_registry.py

Interactive selection modes:

• With questionary (recommended): Checkbox UI with category grouping, token indicators, and paging

- ↑↓ navigate, Space toggle, Enter confirm - Visual indicators: 🟢 <1k tokens, 🟡 1-3k, 🔴 >3k - Grouped by subdirectory

• Without questionary (fallback): Text-based number input

- Enter comma-separated numbers (e.g., 1,3,5) - Type all to migrate everything

What init_registry.py does:

Scans ~/.claude/agents/ and .claude/agents/ for agent files

Displays available agents with metadata

Lets you interactively select which to migrate

Moves selected agents to the registry

Builds search index (registry.json)

Dependencies

• Python: 3.7 or higher
• questionary: Interactive checkbox selection UI with Separator support

The installer automatically installs questionary. If installation fails or pip3 is unavailable, the migration script falls back to text-based input mode.

Manual installation:

pip3 install questionary

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).