Agent Registry

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

Security Scan

The skill's code, hooks, and instructions are coherent with a lazy-loading agent registry: it indexes agents, offers search/get/list CLI tools, and installs a hook that auto-suggests agents on each user prompt; nothing requested is disproportionate to that purpose, though there are operational/privacy considerations to review before installing.

Purpose & Capability

Name/description match the actual behavior: the repository contains a registry index, BM25 search, CLI commands (search/get/list/rebuild/init), and a UserPromptSubmit hook that implements the described lazy-loading and discovery flow. The migration/copy/move functionality is appropriate for a registry tool.

Instruction Scope

The registered hook (hooks/user_prompt_search.js) runs on every user prompt, reads the local registry.json inside the skill, and may inject additionalContext with matching agent names/summaries. This is within the described purpose but is broad in scope (automatic per-prompt behavior) and affects what Claude sees for every conversation; the migration scripts also scan ~/.claude/agents/ and the project's .claude/agents/ to copy or move agent files (move is opt-in).

Install Mechanism

There is no platform-level install spec in the SKILL.md, but the bundle includes an install.sh and recommends using npx skills add or cloning. The installer copies files into ~/.claude/skills/agent-registry/ and will optionally install @clack/prompts only when --install-deps is used. This is reasonable, but the README's npx/npm install suggestions imply pulling code from an external registry/repo—review the remote source before running network-based installers.

Credentials

The skill declares no required env vars or credentials. Telemetry exists but is opt-in (AGENT_REGISTRY_TELEMETRY), and code paths respect opt-out flags per the docs. No secrets or unrelated credentials are requested by the skill.

Persistence & Privilege

The skill installs a per-prompt hook (UserPromptSubmit) which will run automatically when the skill is enabled — this is expected for discovery behavior. always:false and no elevated OS privileges are requested. Because the hook runs on every prompt, users should be aware of the continuous runtime presence and the fact that installing/enabling the skill grants it the ability to inject additionalContext into conversations.

Assessment

This Agent Registry appears to do what it says: index agents, search by intent, and lazily load agent content. Before installing: (1) review the code (especially lib/registry.js and lib/telemetry.js) to verify the path-confinement logic and telemetry behavior; (2) prefer the default non-destructive migration (do not use --move unless you intend to relocate files); (3) note that the hook runs on every prompt and will inject agent suggestions automatically (disable or uninstall if you do not want that behavior); (4) avoid running network installers (npx/npm) unless you trust the remote publisher—if you do use the installer, inspect install.sh first; (5) if you have sensitive agent files, inspect registry.json and any code that resolves agent paths to ensure it cannot be coerced to read files outside the skill's agents/ directory. These checks will reduce operational and privacy risk. If you want additional assurance, share lib/registry.js and lib/telemetry.js for a focused review; that would raise confidence to high.

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?"

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