Agent Registry

# Agent Registry

Claude Code 代理的延迟加载系统。通过按需加载代理来消除“~16k tokens”警告。

## 关键规则

**切勿**假定代理已预加载。始终使用此注册表来发现并加载代理。

## 工作流

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

## 可用命令

| 命令 | 何时使用 | 示例 | |---------|-------------|---------| | `list.js` | 用户询问“我有哪些代理”或需要概览时 | `bun bin/list.js` | | `search.js` | 查找匹配用户意图的代理（始终先执行此操作） | `bun bin/search.js "code review security"` | | `search-paged.js` | 针对大型注册表（300+ 代理）的分页搜索 | `bun bin/search-paged.js "query" --page 1 --page-size 10` | | `get.js` | 加载特定代理的完整指令 | `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. **执行**：遵循已加载代理的指令

## 示例

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

```bash # 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：安装技能

**快速安装（推荐）：**

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

# Discover skills interactively npx skills find

# Update existing skills npx skills update ```

**传统安装：**

```bash # 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` 安装依赖（用于增强 UI 的 `@clack/prompts`）

### 步骤 2：迁移你的代理

运行交互式迁移脚本：

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

**交互式选择模式：**

- **使用 @clack/prompts**（默认）：美观的复选框 UI，支持分组、Token 指示器和分页 - 方向键导航，空格键切换，回车键确认 - 视觉指示器：[绿色] <1k tokens，[黄色] 1-3k，[红色] >3k - 按子目录分组

- **回退模式**：基于文本的数字输入 - 输入逗号分隔的数字（例如 `1,3,5`） - 输入 `all` 迁移所有内容

**init.js 的作用：** 1. 扫描 `~/.claude/agents/` 和 `.claude/agents/` 中的代理文件 2. 显示带有元数据的可用代理 3. 允许你交互式选择要迁移的代理 4. 默认将选定的代理复制到注册表（`--move` 为显式选择加入） 5. 构建搜索索引（`registry.json`）

## 依赖项

- **Bun**（随 Claude Code 一起提供）— 核心功能零额外依赖 - **@clack/prompts**：可选的增强交互式选择 UI（通过 `./install.sh --install-deps` 安装）

## 注册表位置

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

未迁移的代理保留在其原始位置并正常加载（导致 Token 开销）。