← Back to Skills Marketplace
matrixy

Agent Registry

by MaTriXy · GitHub ↗ · v2.0.1
cross-platform ⚠ suspicious
2732
Downloads
0
Stars
9
Active Installs
2
Versions
Install in OpenClaw
/install agent-registry
Description
MANDATORY agent discovery system for token-efficient agent loading. Claude MUST use this skill instead of loading agents directly from ~/.claude/agents/ or ....
README (SKILL.md)

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

Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill Name: agent-registry Version: 2.0.1 The skill is classified as suspicious primarily due to the presence of an anonymous telemetry feature (`lib/telemetry.js`) that sends usage data to an external endpoint (`https://t.insightx.pro`). While this feature is opt-in, well-documented, and designed to be privacy-preserving by not collecting sensitive information, any data exfiltration to an external server, even for benign purposes, introduces a level of risk. Additionally, `SKILL.md` contains strong instructions to the AI agent (e.g., 'Claude MUST use this skill'), which, while intended for efficiency, represents a form of prompt injection. However, the code demonstrates active security hardening, including robust path traversal prevention in `lib/registry.js` for agent file loading, which is a positive indicator against malicious intent.
Capability Assessment
✓ 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.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install agent-registry
  3. After installation, invoke the skill by name or use /agent-registry
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v2.0.1
agent-registry v2.0.1 - Migrated all CLI scripts from Python to faster Bun/JavaScript implementations. - Introduced user prompt hook for agent search (integrated with Claude's plugin system). - Enhanced install process: optional dependency install for improved UI, Bun-first workflow, Python no longer required. - Added modern interactive migration UI using @clack/prompts (with fallback to basic text selection). - Updated docs and commands to reflect new Bun-based CLI; all registry operations via `bun bin/*.js`.
v0.1.0
Initial release: introduces a mandatory agent registry for efficient, lazy loading of Claude agents. - Adds commands for searching, listing, and loading agents by intent. - Workflow eliminates loading all agents upfront, reducing token usage by ~95%. - Includes interactive migration script with both UI and fallback text mode. - Provides installation options via NPX, npm, or local shell script. - Depends on Python 3.7+ and questionary (for interactive selection, with text fallback). - Maintains compatibility—unmigrated agents still load as before.
Metadata
Slug agent-registry
Version 2.0.1
License —
All-time Installs 9
Active Installs 9
Total Versions 2
Frequently Asked Questions

What is 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 .... It is an AI Agent Skill for Claude Code / OpenClaw, with 2732 downloads so far.

How do I install Agent Registry?

Run "/install agent-registry" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Agent Registry free?

Yes, Agent Registry is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Agent Registry support?

Agent Registry is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Agent Registry?

It is built and maintained by MaTriXy (@matrixy); the current version is v2.0.1.

More Skills
self-improving agent
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
⬇ 463283 · by pskoett
Skill Vetter
Security-first skill vetting for AI agents. Use before installing any skill from ClawdHub, GitHub, or other sources. Checks for red flags, permission scope, and suspicious patterns.
⬇ 259410 · by spclaudehome
Polymarket
Query Polymarket prediction markets. Check odds, find trending markets, search events, track price movements.
⬇ 232503 · by joelchance
Self-Improving + Proactive Agent
Self-reflection + Self-criticism + Self-learning + Self-organizing memory. Agent evaluates its own work, catches mistakes, and improves permanently. Use when...
⬇ 200423 · by ivangdavila
Github
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
⬇ 191115 · by steipete
ontology
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linkin...
⬇ 190156 · by oswalpalash

💬 Comments