安装 Agent Skill

Agent Skill 是一份独立发布的技能包，教 Agent 把 tool-bridge 当作运行时能力面来用：先发现当前身份可见的树，再下钻 schema，然后安全调用，并把验证过的经验作为 Feedback 留在路径上。它固化的是工作方式，不是某个实例的静态工具清单。

它维护在独立仓库 TokenRollAI/tool-bridge-skill，与本仓库的网关实现分开演进。

什么时候使用

适合让 Claude Code 一类的 Agent 具备稳定的 tool-bridge 使用习惯：不预设工具列表，每次都从 ~help、~tree 读取当前身份真正可见的能力，再按契约调用。

如果你只是手动探索或写脚本，直接用 tb CLI 或 HTTP 更直接；Skill 的价值在于把「先发现、再调用」这套循环变成 Agent 的默认行为。

安装

npx skills add TokenRollAI/tool-bridge-skill

安装后 Agent 会获得一组围绕 tb 的操作约定。它假设运行环境里已经有可用的 tb，并且调用者会用受限 SK 指向目标实例；具体的 profile、SK 和 BaseURL 由你按权限、SK 与可见性准备，不写进 Skill。

精确的技能内容、命令清单和版本以该仓库的说明为准。

它教 Agent 的循环

Skill 引导 Agent 遵循与人类操作一致的顺序：

确认身份 → 浏览/搜索可见树 → 读取节点 help 索引
        → 下钻工具级 help 取完整 schema → 查看 feedback
        → 最小、可验证地调用 → 记录可复用经验

这套循环的原则见从 ~help 到调用与发现、反馈与协作；Skill 把它们变成 Agent 每次任务的默认动作，而不是一次性提示。

Device Mailbox 的 Agent 快路径

设备命令的 delivery: realtime|mailbox|both 是运行时能力 metadata；tb call --delivery realtime|mailbox|fallback 才是本次调用策略。已知完整 path/schema/delivery，且任务允许设备稍后完成时，Agent 可以只发一次：

tb call device/build-01/ops/sync \
  --arg repository=acme/app \
  --delivery fallback

对 both 命令，gateway 先尝试 realtime，只有明确尚未派发时才入队。Agent 不会在同步调用失败后自行发第二次请求猜测 enqueue，从而避免把“可能已经执行”变成重复副作用。

返回 Mailbox operation 后，默认同步流程到此结束，不启动固定轮询。只有当前用户目标确实需要终态时，才按需执行一次 tb device op get <deviceId> <operationId>。result_unknown 与 expired + executionMayHaveOccurred:true 都不会自动重试；业务幂等已独立证明且用户授权时，才考虑创建新执行。

详细状态与调用面见Device 离线投递与 Mailbox。

给 Agent 的 SK 仍要最小权限

Skill 不改变权限模型。给 Agent 的 SK 应只覆盖它真正需要的路径与动作，deny 优先，无权路径对它表现为 404。不要因为「装了 Skill」就发一把宽泛的 Admin SK；按权限、SK 与可见性签发受限身份，并用独立 profile 验证可见范围符合预期。

Skill 引导 Agent 提交 Feedback 时，也遵循同一边界：读取需要 read，提交和投票还需要 call。SK、token、用户数据和完整敏感 payload 都不应写进 Feedback。

不要和 skillhub 节点混淆

树上的 skillhub NodeKind 与这里说的 Agent Skill 是两回事：

Agent Skill（本页）：一个外部技能包，教 Agent 如何用 tb 操作任意 tool-bridge；用 npx skills add 安装到 Agent 侧。
skillhub 节点：tool-bridge 树内部用于存储与发布 Agent Skill 的节点 kind，是实例里的一类能力来源，见能力树、路径与节点。

一个在 Agent 侧、一个在网关树里；装了 Skill 不等于实例就有 skillhub 节点，反之亦然。

下一步

理解 Skill 引导的发现循环：从 ~help 到调用；
把发现、Feedback 与协作接成习惯：发现、反馈与协作；
手动执行同一套命令：使用 tb CLI；
为 Agent 设计最小权限身份：权限、SK 与可见性。