Agent Registry

核心用法

Agent Registry 是 Claude Code 的强制性 Agent 发现系统，用于替代直接从 ~/.claude/agents/ 或 .claude/agents/ 加载 Agent 的传统方式。其核心设计是延迟加载（lazy loading）：仅在需要时搜索并加载特定 Agent，而非一次性载入全部。

标准工作流

用户请求 → search_agents(意图) → 选择最佳匹配 → get_agent(名称) → 执行

关键命令包括：

• list.js：列举全部可用 Agent
• search.js：根据意图关键词搜索（必须首先执行）
• get.js：加载指定 Agent 的完整指令
• init.js：从旧目录迁移 Agent 到 Registry

显著优点

1. Token 效率革命：相比预加载全部 Agent，可减少约 95% 的上下文窗口占用，彻底消除 "~16k tokens" 警告
2. 即搜即用：支持语义搜索，按相关性评分（0.0-1.0）排序
3. 双级安装：支持用户级（~/.claude/skills/）和项目级（.claude/skills/）部署
4. 零依赖核心：仅需 Bun（Claude Code 内置），可选增强 UI 依赖
5. 交互式迁移：init.js 提供可视化选择界面，支持按 token 消耗分类（绿色 <1k，黄色 1-3k，红色 >3k）

潜在缺点与局限性

• 强制学习成本：用户必须改变旧习惯，"NEVER assume agents are pre-loaded" 的要求增加了认知负担
• 两步操作：任何 Agent 任务都需先 search 后 get，无法直接调用
• 迁移摩擦：存量 Agent 需显式迁移，未迁移的仍按旧方式加载（保留 token 开销）
• 可选依赖陷阱：增强 UI 需手动安装 @clack/prompts，否则降级为数字输入界面

适合人群

• 拥有 10 个以上 Agent 的重度用户
• 频繁遇到 上下文窗口告警 的复杂工作流用户
• 需要按场景动态选择专业 Agent 的开发者（如安全审计、代码审查分离）

常规风险

• 合规风险：Hooks 机制会在每次 UserPromptSubmit 时自动触发搜索脚本（user_prompt_search.js），5 秒超时，失败静默，可能引入延迟
• 版本碎片化：2.0.1 版本与迁移脚本的兼容性需验证，破坏性操作 --move 为显式 opt-in 设计合理但仍有误操作可能
• 安全认证缺失：附注声明 "未执行安全扫描"，生产环境需谨慎评估

核心用法

Agent Registry 是 Claude Code 的强制性 Agent 发现系统，用于解决传统方式加载所有 Agent 导致的上下文窗口爆炸问题。

标准工作流：
1. 从用户请求提取意图关键词
2. 执行搜索：bun bin/search.js "关键词"
3. 查看相关性评分（0.0-1.0），选择最佳匹配
4. 加载完整指令：bun bin/get.js <agent-name>
5. 按加载的 Agent 指令执行任务

关键命令：

• list.js - 列出所有可用 Agent
• search.js - 按意图搜索（首选）
• search-paged.js - 分页搜索（300+ Agent 场景）
• get.js - 获取指定 Agent 完整内容
• init.js - 从传统目录迁移 Agent（交互式选择）

安装与迁移：

• 快速安装：npx skills add MaTriXy/Agent-Registry@agent-registry
• 迁移：bun bin/init.js（支持 --move 破坏性模式）
• 可选依赖：@clack/prompts 提供增强交互 UI

显著优点

1. 极致性能：相比预加载全部 Agent，令牌使用减少约 95%，消除 "~16k tokens" 警告
2. 智能搜索：基于意图的模糊匹配，相关性评分辅助决策
3. 规模友好：分页搜索支持管理 300+ Agent 的大型仓库
4. 迁移友好：交互式 init 脚本支持选择性迁移，保留原有文件结构
5. 零依赖核心：仅需 Bun（Claude Code 内置），可选 UI 库无功能绑定
6. 隐私优先：遥测功能默认禁用，Opt-in 设计符合 GDPR/CCPA

潜在局限

1. 额外步骤：每次使用 Agent 需先执行搜索+加载，增加交互步骤
2. 搜索依赖：结果质量依赖关键词提取准确性，复杂意图可能匹配偏差
3. 迁移成本：现有 Agent 需主动执行 init 迁移，大型仓库迁移耗时
4. 钩子自动搜索开销：UserPromptSubmit 钩子自动执行搜索，增加 5 秒超时成本（虽可跳过但默认启用）
5. 版本管理：Agent 更新后需重建索引（registry.json），暂无自动同步机制

适合人群

• Agent 重度用户：拥有 10+ 自定义 Agent 的开发者
• 上下文敏感场景：处理大型代码库需保留最大上下文窗口
• 团队协作：需要标准化 Agent 发现机制的团队
• 性能优化追求者：对 Claude Code 响应延迟敏感的用户

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 遥测功能 | 低 | 默认禁用，Opt-in 设计，数据完全匿名，可永久关闭 |

| 路径遍历 | 低 | 已防护，文件操作限制在 Skill 目录内 |

| 依赖安全 | 极低 | 仅 @clack/prompts，无已知 CVE |

| Agent 来源 | 中等 | 加载的 Agent 内容本身未验证签名，依赖用户自行审核 |

特别说明：安全认证建议对 bin/get.js 加载的 Agent 文件实施 content_hash 运行时验证（registry.json 已包含哈希字段，待实现）。