agent-registry

Agent Registry

Claude Code Agent 的延迟加载系统。按需加载 Agent，消除“~16k tokens”警告。

关键规则

绝不要假设 Agent 已预加载。 始终使用此注册表来发现并加载 Agent。

工作流

User Request → search_agents(intent) → select best match → get_agent(name) → execute with agent

可用命令

命令	使用时机	示例
list.js	用户询问“我有哪些 Agent”或需要概览时	bun bin/list.js
search.js	查找符合用户意图的 Agent（始终先执行此操作）	bun bin/search.js "code review security"
search-paged.js	对大型注册表（300+ 个 Agent）进行分页搜索	bun bin/search-paged.js "query" --page 1 --page-size 10
get.js	加载特定 Agent 的完整说明	bun bin/get.js code-reviewer

先搜索模式

1. 提取意图关键词：从用户请求中提取
2. 运行搜索：bun bin/search.js "<keywords>"
3. 查看结果：检查相关性得分（0.0-1.0）
4. 按需加载：bun bin/get.js <agent-name>
5. 执行：遵循已加载 Agent 的说明

示例

用户：“你能帮我检查一下我的身份验证代码是否存在安全问题吗？”

# 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

安装

第 1 步：安装技能

快速安装（推荐）：

# Using Skills CLI (recommended)
npx skills add MaTriXy/Agent-Registry@agent-registry

# Discover skills interactively
npx skills find

# Update existing skills
npx skills update

传统安装：

# User-level installation
./install.sh

# OR project-level installation
./install.sh --project

# Optional: install enhanced interactive UI dependency
./install.sh --install-deps

install.sh 的作用：

1. 将技能文件复制到 ~/.claude/skills/agent-registry/
2. 创建空的注册表结构
3. 可通过 --install-deps 选择安装依赖（@clack/prompts，用于增强界面）

第 2 步：迁移你的 Agent

运行交互式迁移脚本：

cd ~/.claude/skills/agent-registry
bun bin/init.js
# Optional destructive mode:
bun bin/init.js --move

交互式选择模式：

• 使用 @clack/prompts（默认）：美观的复选框界面，带有类别分组、令牌指示器和分页

  • 使用方向键导航，空格键切换，Enter 确认
  • 可视化指示：[green] <1k tokens，[yellow] 1-3k，[red] >3k
  • 按子目录分组

• 备用模式：基于文本的数字输入

  • 输入逗号分隔的数字（例如，1,3,5）
  • 输入 all 以迁移全部内容

init.js 的作用：

1. 扫描 ~/.claude/agents/ 和 .claude/agents/ 中的 Agent 文件
2. 显示可用 Agent 及其元数据
3. 允许你以交互方式选择要迁移的 Agent
4. 默认将所选 Agent 复制到注册表（--move 需显式选择）
5. 构建搜索索引（registry.json）

依赖项

• Bun（随 Claude Code 提供）——核心功能无需额外依赖
• @clack/prompts：可选的增强型交互选择界面（通过 ./install.sh --install-deps 安装）

注册表位置

• 全局：~/.claude/skills/agent-registry/
• 项目：.claude/skills/agent-registry/（可选覆盖）

未迁移的 Agent 会保留在原位置并正常加载（会增加令牌开销）。