- name
- agent-registry
- version
- 2.0.1
- description
- |
- hooks
- UserPromptSubmit
- 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 agentAvailable 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?"
# 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 taskInstallation
Step 1: Install the Skill
Quick Install (Recommended):
# Using Skills CLI (recommended)
npx skills add MaTriXy/Agent-Registry@agent-registry
# Discover skills interactively
npx skills find
# Update existing skills
npx skills updateTraditional Install:
# User-level installation
./install.sh
# OR project-level installation
./install.sh --project
# Optional: install enhanced interactive UI dependency
./install.sh --install-depsWhat install.sh does:
- Copies skill files to
~/.claude/skills/agent-registry/ - Creates empty registry structure
- Optionally installs dependencies via
--install-deps(@clack/promptsfor enhanced UI)
Step 2: Migrate Your Agents
Run the interactive migration script:
cd ~/.claude/skills/agent-registry
bun bin/init.js
# Optional destructive mode:
bun bin/init.js --moveInteractive 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
- Copies selected agents to the registry by default (
--moveis explicit opt-in) - 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).