Hermes Agent 中 Skills 与 Tools 的关系分析
基于 hermes-agent-main 源码分析，解答 Skills 是否作为统一 tool 暴露给大模型、具体是哪些 tool、以及内容如何装载。
一、Skills 是否作为统一的 tool 给到大模型？
不是。 Skills 不是 一个统一的 tool。Skills 是通过 3 个独立的 tool 暴露给大模型的，它们都注册在 skills 这个 toolset 下。
这 3 个 tool 定义在 toolsets.py 的 _HERMES_CORE_TOOLS 列表中（第 41 行），意味着它们是默认加载的核心工具之一：
python
# toolsets.py:40-41
_HERMES_CORE_TOOLS = [
# Skills
"skills_list", "skill_view", "skill_manage",
# ...
]它们所属的 toolset skills 也定义在 toolsets.py:164：
python
"skills": {
...
"tools": ["skills_list", "skill_view", "skill_manage"],
}二、具体是哪些 tool？
| Tool 名称 | 作用 | 注册位置 | Schema 定义 |
|---|---|---|---|
skills_list |
列出所有可用技能的名称 + 一句话描述（轻量索引） | tools/skills_tool.py:1526 |
tools/skills_tool.py:1491-1505 |
skill_view |
按需全文加载某个特定技能的 SKILL.md 内容 | tools/skills_tool.py:1564 |
tools/skills_tool.py:1506-1524 |
skill_manage |
创建/编辑/删除技能（Agent 可将成功经验保存为技能） | tools/skill_manager_tool.py:1019 |
tools/skill_manager_tool.py:900-998 |
Handler 实现分别在：
tools/skills_tool.py→skills_list()(line 675) /skill_view()(line 850)tools/skill_manager_tool.py→skill_manage()(line 816)
三、这些 tool 的 Schema 描述里包含了什么？内容是如何装载的？
Skills 内容通过 两级加载 + 三层机制 传递给 LLM：
3.1 第一级：System Prompt 中的紧凑技能索引（初始化时注入）
在 agent/system_prompt.py:169，当检测到 skills_list / skill_view / skill_manage 中任意一个 在 valid_tool_names 里时，调用 build_skills_system_prompt() 构建技能索引并注入 system prompt 的 stable tier：
python
# agent/system_prompt.py:169
has_skills_tools = any(name in agent.valid_tool_names
for name in ['skills_list', 'skill_view', 'skill_manage'])
if has_skills_tools:
skills_prompt = build_skills_system_prompt(
available_tools=agent.valid_tool_names,
available_toolsets=avail_toolsets,
)生成的索引格式如下（agent/prompt_builder.py:983）：
## Skills (mandatory)
Before replying, scan the skills below. If a skill matches or is even
partially relevant to your task, you MUST load it with skill_view(name)
and follow its instructions. Err on the side of loading...
<available_skills>
qa: Quality assurance workflows
- dogfood: Exploratory QA of web apps: find bugs, evidence, reports.
devops:
- kubernetes: Deploy and manage Kubernetes clusters.
- terraform: Provision infrastructure as code.
</available_skills>
Only proceed without loading a skill if genuinely none are relevant.关键点：
- 只包含
name: description (≤60字)一行，不包含完整 SKILL.md 正文 - 通过
_skill_should_show()做条件过滤（依赖的工具/工具集未加载则隐藏、OS 平台不匹配则隐藏等） - 有三层缓存加速构建：L1 内存 LRU → L2 磁盘快照 → L3 全量扫描
3.2 SKILLS_GUIDANCE 行为指导（注入 stable tier）
当 skill_manage 工具可用时，还会往 system prompt 的 stable tier 注入 SKILLS_GUIDANCE（agent/prompt_builder.py:166）：
After completing a complex task (5+ tool calls), fixing a tricky error,
or discovering a non-trivial workflow, save the approach as a
skill with skill_manage so you can reuse it next time.
When using a skill and finding it outdated, incomplete, or wrong,
patch it immediately with skill_manage(action='patch') --- don't wait to be asked.
Skills that aren't maintained become liabilities.注入条件（agent/system_prompt.py:109）：
python
if "skill_manage" in agent.valid_tool_names:
tool_guidance.append(SKILLS_GUIDANCE)3.3 第二级：Tool 的 JSON Schema 描述（随每次 API 调用携带）
三个 tool 的 schema description 分别描述了各自的功能：
skills_list schema （tools/skills_tool.py:1491）：
json
{
"name": "skills_list",
"description": "List available skills (name + description). Use skill_view(name) to load full content.",
"parameters": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Optional category filter to narrow results"
}
},
"required": []
}
}skill_view schema （tools/skills_tool.py:1506）：
json
{
"name": "skill_view",
"description": "Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a 'linked_files' dict showing available references/templates/scripts. To access those, call again with file_path parameter.",
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The skill name (use skills_list to see available skills)..."
},
"file_path": {
"type": "string",
"description": "OPTIONAL: Path to a linked file within the skill..."
}
},
"required": ["name"]
}
}skill_manage schema （tools/skill_manager_tool.py:900）：
较长的 description 包含所有 action（create/patch/edit/delete/write_file/remove_file）的用法指导，以及何时创建/更新技能的规则。
3.4 第三级：LLM 主动调用 skill_view 时按需全文加载（运行时）
这是核心的按需加载机制：
LLM 看到 system prompt 中的紧凑索引
→ 判断某个 skill 相关
→ 调用 skill_view(name="dogfood")
→ tools/skills_tool.py 读取完整的 ~/.hermes/skills/qa/dogfood/SKILL.md
→ 作为 tool result 注入当前 turn 的 messages
→ LLM 看到完整的数千行技能文档绝大多数技能的完整内容永远不进入 context window ，只有被 LLM 主动调用 skill_view 时才加载。
四、完整装载流程图
┌─ System Prompt (stable tier, 会话初始化时一次性构建) ─────────┐
│ SKILLS_GUIDANCE (几句话的行为指导, 仅当 skill_manage 可用) │
│ + 技能索引 (<available_skills> 紧凑列表, 每条 ≤60 字) │
│ + 指令: "scan skills, load with skill_view(name) if relevant" │
└──────────────────────────────────────────────────────────────┘
↓
┌─ 每次 LLM API 调用携带的 tools schema ────────────────────────┐
│ skills_list: 列出所有技能名称+描述 │
│ skill_view: 按 name 加载完整 SKILL.md + linked files │
│ skill_manage: 创建/编辑/删除技能 │
└──────────────────────────────────────────────────────────────┘
↓
┌─ LLM 按需调用 skill_view("xxx") → tool result ────────────────┐
│ 完整 SKILL.md 正文 (500-3000 token) │
│ 作为当轮 tool result 注入 messages │
│ 支持二次调用加载 linked files (references/templates/scripts) │
└──────────────────────────────────────────────────────────────┘五、关键源码文件索引
| 文件 | 作用 |
|---|---|
tools/skills_tool.py |
skills_list / skill_view 的实现与注册 |
tools/skill_manager_tool.py |
skill_manage 的实现与注册 |
tools/skill_usage.py |
技能使用计数（view_count / use_count） |
toolsets.py |
_HERMES_CORE_TOOLS 列表 + skills toolset 定义 |
agent/system_prompt.py |
决定何时注入技能索引 + SKILLS_GUIDANCE |
agent/prompt_builder.py |
build_skills_system_prompt() 构建技能索引；SKILLS_GUIDANCE 文本 |
model_tools.py |
get_tool_definitions() 将工具注入 LLM schema |
agent/agent_init.py |
AIAgent.__init__ 中调用 get_tool_definitions() |
文档生成时间：2026-06-16 | 源码版本：hermes-agent-main