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

code

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

•Extract intent keywords from user request
•Run search: bun bin/search.js "<keywords>"
•Review results: Check relevance scores (0.0-1.0)
•Load if needed: bun bin/get.js <agent-name>
•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

What install.sh does:

•Copies skill files to ~/.claude/skills/agent-registry/
•Creates empty registry structure
•Installs npm dependencies (@clack/prompts for interactive UI)

Step 2: Migrate Your Agents

Run the interactive migration script:

bash

cd ~/.claude/skills/agent-registry
bun bin/init.js

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:

•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

•Bun (ships with Claude Code) — zero additional dependencies for core functionality
•@clack/prompts: Interactive selection UI (installed via npm/bun)

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