智能体 | Nanobot 技能和工具使用

在实际 AI 智能体落地场景中，会遇到两类困境：空有一堆工具能力却难以融入业务场景实现中，或是缺少可调用的基础工具，难以快速搭建贴合业务的智能工作流。

在智能体落地中，工具 Tool 作为底层原子执行能力，负责完成基础实操动作；技能 Skills 依托工具做场景流程封装，沉淀领域经验与最优执行逻辑，二者各司其职、协同联动。

本文通过拆解 Nanobot 架构内 Tool 与 Skill 的核心实现、本质差异与使用逻辑，通过多维度对比理清二者区别，助力搭建可定制、高可用的 AI 智能体应用。

1，工具的定义和使用

工具是原子执行单元，对应可被 LLM 调用的函数或者API，如执行 Shell、读写文件、网络请求、数据库查询等。

特点：无状态、可复用、细粒度、由框架统一注册与调度。

比如典型的常用内置工具有：

• • run_shell：执行系统命令
• • read_file/write_file：文件读写
• • http_request：HTTP 调用
• • cron：定时任务

注册机制：框架启动时扫描内置 / 自定义工具，自动生成工具定义（JSON Schema）供 LLM 理解参数与用途。

工具实现的类图：

图 1，工具类的 UML 图

所用的工具实现必须继承工具基类 Tool，其定义了工具需要实现的基本方法。工具的管理通过ToolRegistry 实现，比如，工具注册，获取工具定义，工具参数的校验，工具执行等等。

其中重要的功能是，将函数的参数转换为 openai 工具调用的格式，当 llm 生成需要调用的工具后，需要再把 openai 格式的参数转换为函数需要的格式。

工具使用的流程

图 2，工具使用的时序图

在 Agent 主循环中获取所有工具的描述，并转换为 openai 工具协议格式，调用大模型生成工具列表，然后将参数转换为函数需要的格式，进行工具调用，将工具执行的结果放到大模型的上下文中，进一步请求大模型生成结果。

更一般通用调用流程（ReAct 循环）：

• • LLM 接收用户问题，生成工具调用请求（含工具名、参数）。
• • 框架校验权限与参数，异步执行工具。
• • 结果返回 LLM，进入下一轮思考 / 调用，直至完成。

以上的流程通常以 ReAct 循环的思想进行。即ReAct 循环驱动技能执行，框架基于 ReAct（Reason + Act） 模式，LLM 根据 SKILL.md 自主判断是否触发技能、调用工具、迭代执行，无需硬编码流程。

更进一步的了解，需要在openai 工具协议的基础上进行理解。

2，openAI 工具协议

OpenAI 在 Chat Completions API 里定义了一套标准化工具调用 JSON 协议，让 LLM 可以：

自然语言思考 → 输出结构化 JSON 指令 → 外部程序执行 → 结果回传给 LLM → 继续思考

它是目前所有 Agent 框架都兼容的行业标准接口。

1）请求时：把工具描述发给 LLM（tools 字段）

代码语言：javascript

{
  "model":"gpt-4o",
"messages":[...],
"tools":[
    {
      "type":"function",
      "name":"run_shell",
      "description":"执行系统命令",
      "parameters":{
        "type":"object",
        "properties":{
          "cmd":{"type":"string","description":"要执行的命令"}
        },
        "required":["cmd"]
      }
    }
]
}

Tools 字段相关参数定义：

• • type: function：固定，代表这是可调用工具
• • name：工具唯一标识
• • description：给 LLM 看的自然语言说明
• • parameters：JSON Schema，强约束参数类型、必填、描述

2）LLM 返回：工具调用指令（tool_calls）

代码语言：javascript

{
  "choices":[
    {
      "message":{
        "role":"assistant",
        "tool_calls":[
          {
            "id":"call_123",
            "type":"function",
            "function":{
              "name":"run_shell",
              "arguments":"{"cmd":"ls -l"}"
            }
          }
        ]
      }
    }
]
}

3）应用层回传：工具执行结果（role: tool）

代码语言：javascript

{
  "role": "tool",
  "tool_call_id": "call_123",
  "name": "run_shell",
  "content": "file1.txtnfile2.txt"
}

协议中，传入的工具参数必须转换到 openai 规定的 json 格式，且需要根据大模型生成的结果，将其转换为框架中调用工具的实际参数。这一切的工作都是围绕既定的openai 工具调用协议进行。

3，技能使用介绍

3.1，技能定义和调用

技能是业务能力单元，通过声明式配置（SKILL.md）面向特定场景，封装的一组工具调用逻辑。

• • 特点：有状态、场景化、高内聚、LLM 可直接理解与触发。
• • 目录结构（文件系统注册，无需代码）：

代码语言：javascript

nanobot/workspace/skills/
└── 自定义技能名/          # 技能唯一标识（英文小写，无空格）
    ├── SKILL.md           # 核心：LLM识别文档、规则、流程、入参出参
    ├── scripts/
    │   └── main.py        # 技能核心执行代码
    └── resources/         # 可选：静态配置、模板、本地资源

技能整体使用全流程：

用户输入 → 意图解析匹配技能 → 加载技能配置 → 初始化执行上下文 → 技能内调用工具 → 业务逻辑执行 → 结果整理输出

匹配阶段：框架扫描全局skills目录，读取所有SKILL.md描述，LLM 根据用户指令语义匹配对应技能

加载阶段：匹配成功后自动加载技能脚本、依赖资源、权限配置

执行阶段：注入SkillContext上下文，运行技能入口main函数，通过上下文调用内置 / 自定义工具

回调阶段：执行结果回传给 LLM，完成对话闭环

销毁阶段：单次任务结束，释放上下文，无冗余常驻

3.2，渐进式加载

两类 Skill 的不同加载策略

策略 A：always: true — 强制全量加载

代码语言：javascript

name: memory
always: true    ← 关键标志

行为：每次构建 system prompt 时，完整 SKILL.md 内容直接嵌入。

适用场景：Agent 必须始终了解的基础规则。目前只有 memory 使用此策略。

代码语言：javascript

always_skills = self.skills.get_always_skills()  # ["memory"]
if always_skills:
    always_content = self.skills.load_skills_for_context(always_skills)
    parts.append(f"# Active Skillsnn{always_content}")  # 完整文本注入

策略 B：默认 — 只加载目录摘要

行为：只向 LLM 展示一个 XML 形式的技能目录，告诉 LLM "有哪些技能可用"，但不把内容全部塞进去（避免 token 浪费）。

生成的 XML 示例：

代码语言：javascript

  
    github
    Interact with GitHub using the gh CLI...
    /.../nanobot/skills/github/SKILL.md


    tmux
    Remote-control tmux sessions...
    /.../nanobot/skills/tmux/SKILL.md
    CLI: tmux

  ...

配合模板 prompt 中 `skills_section.md 内容：

代码语言：javascript

# Skills
The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
Skills with available="false" need dependencies installed first...
{{ skills_summary }}

通过以上的两种策略，实现了必备技能常驻，可选技能通过提供技能列表，实现运行时按需加载。

比如：当用户问 "帮我查一下 GitHub PR 状态" 时，LLM 看到 skills 目录中有 github，然后调用技能 read_file("skills/github/SKILL.md") 工具来读取完整教程。

3.3，技能 skill 相关思考

思考 1：技能设计的业务逻辑

设计点	实现方式	解决的业务问题
Skill = Markdown	纯文本教程，不是代码	零开发成本扩展能力
渐进式加载	always=true 全量 + 其余只展示目录	控制 token 消耗，避免 prompt 膨胀
按需读取	LLM 通过 read_file tool 主动读取	只有相关时才消耗 token
双源覆盖	workspace > builtin	用户可自定义/覆盖内置 skill
依赖门控	frontmatter declares bins/env	自动检测可用性，引导安装
自举能力	skill-creator skill 教 LLM 创建新 skill	生态系统可自我增长
ClawHub 注册表	clawhub skill 教 LLM 搜索安装	社区共享，类似 npm for skills

思考2：为什么通过 xml 提供现有技能的列表

原因有四点：

• • 结构化数据在 LLM context 中最稳定
• • 与 Markdown 天然共存
• • LLM 训练数据中 XML 占比高
• • 可扩展性 —— 未来加字段零成本

选 XML 的本质原因是，这是一个"给机器读的结构化索引"，不是给人读的文档。

思考 3：技能中的元技能使用

skill-creator 是元技能（meta-skill）它教 LLM 如何创建其他 skill，形成自举能力。

当使用大模型自身创建技能时，大模型会调用元技能，生成需要的技能目录。具体流程如下：

代码语言：javascript

用户: "帮我创建一个 docker 部署的 skill"
  ↓
LLM 读取 skill-creator/SKILL.md（详细指南）
  ↓
LLM 学会如何写 frontmatter、组织 references、编写 scripts
  ↓
LLM 调用 scripts/init_skill.py docker-deploy --path ./workspace/skills
  ↓
LLM 编写 SKILL.md 和可选资源文件
  ↓
LLM 调用 scripts/package_skill.py 打包
  ↓
产出: docker-deploy.skill（可分发的新 skill）

总结：

本文主要介绍了，在智能体中工具和技能的使用，工具是基础的原子能力，技能是面向特定场景在原子能力上流程的封装。以下是 tool 和 skill 的比较。

维度	Tool	Skill
本质	Python 代码，可执行	Markdown 文档，可阅读
提供能力	底层原子操作（执行命令、读写文件）	上层领域知识（工作流、最佳实践）
扩展方式	写 Python 类继承 BaseTool	创建目录 + 写 SKILL.md
加载时机	注册后立即可用	渐进式加载（元数据→正文→资源）
Token 成本	低（只有 schema 定义）	可控（渐进式设计）

一句话总结：Tool 给 Agent 手（能做什么），Skill 给 Agent 脑（知道怎么做）。

Nanobot 的工具和技能系统以 “极简架构 + 声明式配置 + ReAct 驱动“ 为核心，实现了低门槛扩展、本地可控、高效执行的 AI Agent 能力。工具是原子执行单元，技能是场景化能力封装，二者结合让用户无需复杂编码即可构建隐私安全、高度定制的智能助手与自动化工作流。