AI Agent: Design Principles and Engineering Practice is an open-source book that explains how AI agents combine language models, context, and tools, with accompanying experiments and code. It is intended for readers studying the principles and engineering of AI agents, from fundamentals through production use. The catalogue skills support coding-agent work related to the book's subject matter.
Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add bojieli/ai-agent-book --skill tool-discoverygit clone --depth 1 https://github.com/bojieli/ai-agent-bookWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/bojieli/ai-agent-book/tool-discovery)<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/tool-discovery"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/tool-discovery/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/tool-discovery"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/tool-discovery.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00104 | $0.02578 |
| Opus 5.5 | $0.00042 | $0.01031 |
| Sonnet 5.5 | $0.00021 | $0.00516 |
| Haiku 4.5 | $0.00010 | $0.00258 |
Grade A, and why
tool-discovery scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 22d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 87 lines — stays where its author put it; the contents beside it link to each section on GitHub.
工具发现与渐进式加载
何时使用
- 接入的 MCP 服务器越来越多，system prompt 被工具 schema 占掉几千到几万 token
- 工具库增长到上百个，模型开始选错工具、漏掉工具
- 设计"只暴露索引、按需加载定义"的工具披露层
- 实现主动工具发现：Agent 声明能力缺口 → 系统语义匹配 → 动态注入 schema
- 需要在工具数量、token 成本、准确率之间做架构取舍
- 动态加载工具后 Prompt Cache 命中率下降，需要定位原因
- 为小参数量模型（4B 级）设计可用的上百工具接入方案
核心原则
- 规模本身伤害正确性。 工具数超过 100 个时，即使最先进模型也容易在工具选择上出错；全部平铺还占大量 token，且每次工具集变动都击穿 KV Cache。
- 三层答案，一层比一层"按需"：① 层次化组织 + 按需加载（定义事先备好，不全量注入）；② 主动工具发现（Agent 意识到缺口，主动声明需求，系统匹配注入）；③ Skills（不把工具当正式定义，当可随手翻阅的参考资料）。
- 披露策略与能力形态是两个独立决策。 挂着几百个 MCP 工具的服务器可以只暴露一份索引；二十来个 skill 也可能需要分层检索。别把"全量常驻上下文"当默认。
- 只暴露索引是第一件事。 Cursor 的做法：把工具描述同步到文件夹，Agent 默认只看工具名索引，需要时再查具体定义。A/B 测试显示 MCP 相关任务总 token 减少 46.9%。
- 约 200 token 的代理工具（pi-mcp-adapter）就能支撑"搜索 → 查看定义 → 调用"的完整按需发现流程，MCP 服务器还可延迟到首次使用才启动。是否用 MCP 作协议与会话开始时是否暴露全部工具定义，是两个独立决策。
- 一次性检索有内在局限。 检索式预筛选按用户的初始查询做一次匹配，而 "Debug the file" 这类请求实际牵出文件访问、代码分析、命令执行的多步骤跨领域工具链，任务开始时无法预见全部需求。
- 匹配必须层次化。 工具按服务器（类似 App）分组，先定位服务器、再在服务器内匹配工具，把搜索空间从"数千个工具"缩到"数十个服务器 × 每个数十个工具"，既省算力也减少跨领域语义混淆。
- schema 固定原位，静态前缀只增不改。 新工具的完整 schema 追加到上下文末尾并固定在首次注入的位置，作为普通历史消息继续命中缓存——"工具定义必须在上下文最前面"不再是铁律。
实践模式
1. 方案选型（按工具数量与场景）
| 工具规模 | 推荐方案 |
|---|---|
| 十几个 | 全量注入，无需额外机制 |
| 几十个 | 只暴露索引，按需查定义 |
| 上百个 | 检索式预筛选（top-k 后注入） |
| 上百至上千 | 主动工具发现（元工具 + 两层语义路由）或 Skills 渐进式披露 |
| 上千 | Skills / Skill Hub；专用工具须另建索引层 |
层次化组织按信息源性质分类，并在系统提示词中显式说明，帮助 LLM 快速定位工具组：搜索工具（主动查找：网络/知识库/文件搜索）、读取工具（从已知位置提取：网页阅读、文档读取、DB 查询）、解析工具（处理非结构化数据：OCR、视频分析、音频转录）、查询工具（访问结构化数据源：天气、股票、公开数据库 API）。
2. 渐进式工具加载五步流程（核心机制）
- 索引：启动时只注入一份薄索引——工具/服务器的
name+description（数百 token），不注入完整 schema。 - 声明需求：Agent 在思考中意识到能力缺口，生成结构化请求块声明"我需要什么能力"，例如
<tool_request>server: GitHub for repository operations; tool: search repositories by keyword</tool_request>。系统提示词中只保留少数基础工具（web_search、code_interpreter）加一个discover_tools元工具。 - 语义匹配：系统用离线构建、支持增量更新的嵌入索引做服务器级 → 工具级两层路由，返回 3-5 个候选工具及其完整 schema。
- 注入 schema：新工具 schema 追加到上下文末尾（作为普通 user/assistant 消息），此后固定在轨迹原位置；状态栏只维护一份简短的工具名列表。后续轮次作为普通历史命中缓存。
- 调用：Agent 用注入的工具执行；再次遇到同类需求时直接复用已加载工具，无需重复加载。
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 22d ago First seen · 87 lines · 104 tokens per session scan A 2ec51723dba6
tool-discovery is a skill published in the GitHub repository bojieli/ai-agent-book (54,406 stars, last pushed 7d ago), licensed Apache-2.0. It adds 104 tokens to every session and 2,578 once invoked, about $0.0004 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-24.
Other skills, from other repositories
remem-mcp
Long-term memory for coding agents. Auto-applies at the start of any coding task — recall past context before answering, capture decisions/learnings/fixes after work, use CodeGraph instead of grep for symbol lookup. Invoke when you see [remem-mcp] in your context or when starting any non-trivial coding work.
tura
Work in the Tura agent-runtime repository. Use for Tura architecture, Rust backend, GUI/TUI, prompts, commands, providers, sessions, documentation, tests, packaging, and release work in this directory.
acontext-installer
Install Acontext, Login & Init Acontext Project, Add Skill Memory to Agent.
ccc
This skill should be used when code search is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'update the…
openlore
Query and publish to an OpenLore knowledge repository over SSH using ordinary shell commands. Use when a task needs project documentation, runbooks, shared team knowledge, or a place to publish findings.
system-monitor
Monitor system health: CPU, memory, disk, processes, and network. Alert on thresholds via any channel.