Claude 官方 Agent 按需加载系统，解决 16k tokens 上下文溢出问题，支持智能搜索与延迟加载，可节省约 95% 的 token 消耗。
说明：
## 核心用法
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 消耗分类（绿色 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 设计合理但仍有误操作可能
– **安全认证缺失**：附注声明 “未执行安全扫描”，生产环境需谨慎评估
