🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Agent Registry
πŸ¦€ ClawHub

Agent Registry

by @matrixy

MANDATORY agent discovery system for token-efficient agent loading. Claude MUST use this skill instead of loading agents directly from ~/.claude/agents/ or ....

Versionv2.0.1
Downloads3,771
#clawhub
TERMINAL
clawhub install agent-registry

πŸ“– About This Skill

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 "" 3. Review results: Check relevance scores (0.0-1.0) 4. Load if needed: bun bin/get.js 5. 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 task

Installation

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 update

Traditional Install:

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

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

    πŸ’‘ Examples

    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 task