Hermes Agent Skill 机制深入理解
来源：互联网 2026-07-16 20:03:04HermesAgent的Skill机制是一套知识注入流程，包含发现索引、触发加载、预处理、Prompt注入和LLM响应五个阶段。以SKILL.md文件为核心，通过YAMLfrontmatter声明元数据，支持条件激活、平台过滤、安全检测等特性。触发方式包括LLM自主调用、Slash命令和CLI预加载，预处理涉及模板变量替换与Shell展开。
# Hermes Agent 的 Skill 机制详解：从发现到注入的完整流程
如同此前讨论的内容，Hermes Agent 的 Skill 系统本质上是一套完整的知识注入机制。它并非简单的文件读取，而是经历了一个从“找到它”到“用上它”的完整流程。具体而言，该流程包含**五个阶段：发现索引、触发加载、预处理、Prompt 注入，最后才是 LLM 响应**。核心载体是 `SKILL.md` 文件，通过 YAML frontmatter 声明元数据，支持条件激活、平台过滤、安全检测等一系列特性。
## 1. Skill 目录结构
先了解其目录组织方式，结构较为直观：
```
~/.hermes/skills/
├── category-a/
│ └── skill-name/
│ ├── SKILL.md # 必需：主文件
│ ├── references/ # 可选：参考资料
│ ├── templates/ # 可选：模板文件
│ ├── scripts/ # 可选：脚本文件
│ └── assets/ # 可选：资源文件
├── category-b/
│ └── another-skill/
│ └── SKILL.md
└── ...
```
**几个关键点值得注意**：
- 支持任意深度的子目录嵌套，系统通过 `os.walk` 递归扫描，分类层级方面无需过多担忧
- 子目录仅用于分类组织，不影响索引结果
- 四个目录会被自动排除：`.git`、`.github`、`.hub`、`.archive`
## 2. 完整生命周期（5 阶段）
### 2.1 Phase 1：发现与索引（启动时）
当 Agent 启动时，按以下路径扫描所有 Skill：
```
get_all_skills_dirs()
├── ~/.hermes/skills/ # 本地目录（始终在前）
└── skills.external_dirs # 外部目录（config.yaml 配置）
↓
iter_skill_index_files() # 递归扫描所有 SKILL.md
↓
parse_frontmatter() # 解析 YAML 元数据
↓
过滤规则：
├── skill_matches_platform() # 平台兼容性检查
├── get_disabled_skill_names() # 禁用列表过滤
└── _skill_should_show() # 条件激活规则
↓
build_skills_system_prompt() # 生成分类索引 Prompt
```
此处采用了两级缓存机制来提升效率，目的是减少重复扫描磁盘的负担：
| 层级 | 类型 | 容量 | Key |
|------|------|------|-----|
| L1 | 进程内 LRU 缓存 | 8 entries | (skills_dir, external_dirs, tools, toolsets, platform, disabled) |
| L2 | 磁盘快照 | 持久化 | `.skills_prompt_snapshot.json`（mtime/size 验证） |
生成的 System Prompt 格式如下：
```
## 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.
category-a:
- skill-name: brief description
- another-skill: another description
Only proceed without loading a skill if genuinely none are relevant to the task.
```
### 2.2 Phase 2：触发（3 种方式）
这是整个机制中最关键的一环——Skill 如何被激活？有三种途径：
#### 方式 A：LLM 自主调用（主要路径）
这是最核心的触发方式，也是设计上期望的主要路径：
```
System Prompt 引导：
"Before replying, scan the skills below... MUST load with skill_view(name)"
↓
LLM 判断任务与 skill 相关
↓
tool_call: skill_view(name="skill-name")
```
触发条件较为灵活：
- Skill 名称或描述与用户请求匹配
- Skill 的 `description` 字段包含关键词
- LLM 自主判断“部分相关”即应加载——这意味着描述写得好的 Skill 更容易被命中
#### 方式 B：Slash 命令（用户显式调用）
当用户想直接指定某个 Skill 时，可按如下方式操作：
```
用户输入：/skill-name some instruction
↓
scan_skill_commands() # 扫描所有 SKILL.md 生成命令映射
↓
匹配 /skill-name
↓
build_skill_invocation_message() # 构建触发消息
```
**Skill 命令命名规则**：名称会经过规范化处理——小写，空格/下划线转连字符，去除非法字符。例如 `My Skill` 变为 `/my-skill`。
#### 方式 C：CLI 预加载（Session 启动时）
另一种方式是在启动时直接指定：
```
hermes --skills skill-name
```
```
build_preloaded_skills_prompt()
↓
注入到 session prompt 开头
```
### 2.3 Phase 3：加载与预处理
当 Skill 被触发后，进入实质性的加载阶段。`skill_view()` 的执行流程较为严谨：
```
skill_view(name)
├── 解析 qualified name # plugin:skill → 路由到 plugin 系统
├── 目录搜索（first match wins） # local → external
│ ├── 直接路径：search_dir/name/SKILL.md
│ ├── 分类路径：search_dir/category/name/SKILL.md
│ └── 名称匹配：遍历所有 SKILL.md 比对目录名
├── 安全检查
│ ├── 路径穿越检测（防止 .. 攻击）
│ └── prompt injection 模式扫描
├── 平台/禁用检查
├── 前置条件检查
│ ├── 环境变量（prerequisites.env）
│ └── 凭证文件（prerequisites.credential_files）
├── preprocess_skill_content()
│ ├── 模板变量替换：${HERMES_SKILL_DIR} → 绝对路径
│ └── inline shell 展开：!`cmd` → 执行结果
├── 收集 linked_files
│ ├── references/*.md
│ ├── templates/*.yaml
│ ├── scripts/*.py
│ └── assets/*
└── 返回 JSON：
{
"success": true,
"name": "skill-name",
"content": "",
"linked_files": {"references": [...], "templates": [...]},
"skill_dir": "/path/to/skill",
"setup_needed": false,
"readiness_status": "a vailable"
}
```
预处理机制有两个值得关注的亮点：
**模板变量替换**：
```
${HERMES_SKILL_DIR} → skill 的绝对路径
${HERMES_SESSION_ID} → 当前会话 ID
```
**Inline Shell 展开**（需配置启用）：
```
!`ls -la ${HERMES_SKILL_DIR}/scripts/`
→ 替换为命令执行结果
```
### 2.4 Phase 4：Prompt 注入
加载完成后，Skill 内容需要以合适的方式注入到对话上下文中。根据触发方式不同，注入方式也有所区别：
#### 方式 A：LLM tool call 返回
```
tool 返回 JSON
↓
作为 tool_result 注入 conversation history
↓
LLM 在下一轮看到完整 skill 内容
```
#### 方式 B：Slash 命令消息构建
```
_build_skill_message()
├── [IMPORTANT：The user has invoked the "xxx" skill...]
├──
├── [Skill directory：/path/to/skill]
├── [Skill config：key = value] # 配置变量注入
├── [Skill setup note：...] # 安装提示
├── [This skill has supporting files：] # 支持文件列表
│ ├── references/api.md → /path/to/references/api.md
│ └── scripts/run.py → /path/to/scripts/run.py
└── The user has provided the following instruction：...
↓
作为 user message 注入 → LLM 响应
```
#### 方式 C：CLI 预加载
```
[IMPORTANT：The user launched this CLI session with "xxx" ...]
↓
追加到 system prompt 的 prompt_parts
```
### 2.5 Phase 5：LLM 响应与执行
最后，LLM 开始基于 Skill 内容进行响应：
```
LLM 接收包含 skill 内容的 message
├── 遵循 skill 中的 instructions
├── 可通过 skill_view(name, file_path) 加载 supporting files
├── 执行 skill 中的 scripts（通过 skill_dir 绝对路径）
├── 使用 skill 声明的配置变量
└── 任务完成后可选：skill_manage(action='patch') 更新 skill
```
## 3. Skill 元数据（YAML Frontmatter）
每个 `SKILL.md` 文件的开头，都有一段 YAML frontmatter 来声明元数据。其中的字段配置直接决定 Skill 的行为：
```
---
name：skill-name
description： "简短描述（≤1024 字符）"
version： 1.0.0
author： Author Name
license： MIT
platforms： [macos, linux] # 可选：平台限制
metadata：
hermes：
tags： [tag1, tag2]
related_skills： [skill-a, skill-b]
fallback_for_toolsets： [web] # 当 web toolset 可用时隐藏
fallback_for_tools： [web_fetch] # 当 web_fetch tool 可用时隐藏
requires_toolsets： [browser] # 当 browser toolset 不可用时隐藏
requires_tools： [browser_click] # 当 browser_click tool 不可用时隐藏
config： # 配置变量声明
- key： api_endpoint
description： API endpoint URL
default： "https://api.example.com"
prompt： Enter API endpoint
prerequisites：
env：
- name： API_KEY
description： API key for authentication
credential_files：
- path： ~/.config/skill/credentials.json
description： Credentials file
---
```
## 4. 条件激活规则
该机制是 Skill 灵活性的核心所在。通过几个字段，可以精确控制 Skill 在什么条件下出现，什么条件下隐藏：
| 字段 | 含义 | 示例 |
|------|------|------|
| fallback_for_toolsets | 当指定 toolset 可用时隐藏此 skill | 有 web toolset 时不需要 web-fallback skill |
| fallback_for_tools | 当指定 tool 可用时隐藏此 skill | 有 web_fetch tool 时不需要备用方案 |
| requires_toolsets | 当指定 toolset 不可用时隐藏 | 没有 browser toolset 时浏览器 skill 不可用 |
| requires_tools | 当指定 tool 不可用时隐藏 | 没有 git tool 时 git 相关 skill 不可用 |
## 5. 安全机制
在处理外部注入的内容时，安全是不可忽视的环节。
### 5.1 Prompt Injection 检测
系统会扫描以下常见攻击模式：
- `ignore previous instructions`
- `disregard your instructions`
- `you are now`
- `system prompt：`
- ``
**处理方式**上，系统区分了两种场景：
- Context 文件注入：**拒绝加载**并警告
- Skill 内容注入：**记录警告但仍加载**（因为 Skill 被视为可信来源）
### 5.2 路径安全
- 防止路径穿越攻击（`..`）
- 验证解析路径仍在 skill 目录内
- 禁止访问 skill 目录外的文件
## 6. 关键文件职责
整个 Skill 机制的实现分散在多个文件中，各司其职：
| 文件 | 职责 |
|------|------|
| hermes_constants.py | get_skills_dir() → ~/.hermes/skills/ 路径解析 |
| agent/skill_utils.py | 核心工具：frontmatter 解析、平台匹配、禁用列表、外部目录、条件提取、文件迭代 |
| agent/prompt_builder.py | build_skills_system_prompt() 生成分类索引，两级缓存，_skill_should_show() 条件过滤 |
| agent/skill_commands.py | Slash 命令扫描、消息构建、CLI 预加载 |
| agent/skill_preprocessing.py | 模板变量替换、inline shell 展开 |
| tools/skills_tool.py | Tool 注册（skills_list, skill_view）、skill 加载、安全检查、linked_files 发现 |
| model_tools.py | Tool 注册触发、toolset 过滤 |
| tools/registry.py | Tool 注册机制，registry.register() 统一注册 schema + handler |
| run_agent.py | Agent 循环中调用 build_skills_system_prompt()，注入 system prompt |
## 7. 优化与最佳实践
### 7.1 Skill 设计原则
1. **描述清晰**：`description` 字段是 LLM 判断是否加载的主要依据，应包含关键词
2. **触发词明确**：在 description 中列出典型触发场景
3. **条件激活合理使用**：避免与内置 tool 冲突，使用 `fallback_for_*` 声明备选关系
4. **支持文件组织**：将参考资料、模板、脚本放在对应子目录中
5. **配置变量声明**：需要用户配置的参数应在 frontmatter 中声明
### 7.2 性能优化
1. **两级缓存**：避免重复扫描文件系统
2. **条件过滤前置**：在索引阶段就过滤掉不兼容的 skill
3. **延迟加载**：仅加载与当前任务相关的 skill 内容
总体来看，这套 Skill 机制的设计思路清晰明确：通过明确定义的生命周期和灵活的触发方式，让知识注入既有章可循，又不会显得死板。理解了这个流程，再去开发或优化自己的 Skill，就有了清晰的方向。
## 1. Skill 目录结构
先了解其目录组织方式，结构较为直观：
```
~/.hermes/skills/
├── category-a/
│ └── skill-name/
│ ├── SKILL.md # 必需：主文件
│ ├── references/ # 可选：参考资料
│ ├── templates/ # 可选：模板文件
│ ├── scripts/ # 可选：脚本文件
│ └── assets/ # 可选：资源文件
├── category-b/
│ └── another-skill/
│ └── SKILL.md
└── ...
```
**几个关键点值得注意**：
- 支持任意深度的子目录嵌套，系统通过 `os.walk` 递归扫描，分类层级方面无需过多担忧
- 子目录仅用于分类组织，不影响索引结果
- 四个目录会被自动排除：`.git`、`.github`、`.hub`、`.archive`
## 2. 完整生命周期（5 阶段）
### 2.1 Phase 1：发现与索引（启动时）
当 Agent 启动时，按以下路径扫描所有 Skill：
```
get_all_skills_dirs()
├── ~/.hermes/skills/ # 本地目录（始终在前）
└── skills.external_dirs # 外部目录（config.yaml 配置）
↓
iter_skill_index_files() # 递归扫描所有 SKILL.md
↓
parse_frontmatter() # 解析 YAML 元数据
↓
过滤规则：
├── skill_matches_platform() # 平台兼容性检查
├── get_disabled_skill_names() # 禁用列表过滤
└── _skill_should_show() # 条件激活规则
↓
build_skills_system_prompt() # 生成分类索引 Prompt
```
此处采用了两级缓存机制来提升效率，目的是减少重复扫描磁盘的负担：
| 层级 | 类型 | 容量 | Key |
|------|------|------|-----|
| L1 | 进程内 LRU 缓存 | 8 entries | (skills_dir, external_dirs, tools, toolsets, platform, disabled) |
| L2 | 磁盘快照 | 持久化 | `.skills_prompt_snapshot.json`（mtime/size 验证） |
生成的 System Prompt 格式如下：
```
## 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.
category-a:
- skill-name: brief description
- another-skill: another description
Only proceed without loading a skill if genuinely none are relevant to the task.
```
### 2.2 Phase 2：触发（3 种方式）
这是整个机制中最关键的一环——Skill 如何被激活？有三种途径：
#### 方式 A：LLM 自主调用（主要路径）
这是最核心的触发方式，也是设计上期望的主要路径：
```
System Prompt 引导：
"Before replying, scan the skills below... MUST load with skill_view(name)"
↓
LLM 判断任务与 skill 相关
↓
tool_call: skill_view(name="skill-name")
```
触发条件较为灵活：
- Skill 名称或描述与用户请求匹配
- Skill 的 `description` 字段包含关键词
- LLM 自主判断“部分相关”即应加载——这意味着描述写得好的 Skill 更容易被命中
#### 方式 B：Slash 命令（用户显式调用）
当用户想直接指定某个 Skill 时，可按如下方式操作：
```
用户输入：/skill-name some instruction
↓
scan_skill_commands() # 扫描所有 SKILL.md 生成命令映射
↓
匹配 /skill-name
↓
build_skill_invocation_message() # 构建触发消息
```
**Skill 命令命名规则**：名称会经过规范化处理——小写，空格/下划线转连字符，去除非法字符。例如 `My Skill` 变为 `/my-skill`。
#### 方式 C：CLI 预加载（Session 启动时）
另一种方式是在启动时直接指定：
```
hermes --skills skill-name
```
```
build_preloaded_skills_prompt()
↓
注入到 session prompt 开头
```
### 2.3 Phase 3：加载与预处理
当 Skill 被触发后，进入实质性的加载阶段。`skill_view()` 的执行流程较为严谨：
```
skill_view(name)
├── 解析 qualified name # plugin:skill → 路由到 plugin 系统
├── 目录搜索（first match wins） # local → external
│ ├── 直接路径：search_dir/name/SKILL.md
│ ├── 分类路径：search_dir/category/name/SKILL.md
│ └── 名称匹配：遍历所有 SKILL.md 比对目录名
├── 安全检查
│ ├── 路径穿越检测（防止 .. 攻击）
│ └── prompt injection 模式扫描
├── 平台/禁用检查
├── 前置条件检查
│ ├── 环境变量（prerequisites.env）
│ └── 凭证文件（prerequisites.credential_files）
├── preprocess_skill_content()
│ ├── 模板变量替换：${HERMES_SKILL_DIR} → 绝对路径
│ └── inline shell 展开：!`cmd` → 执行结果
├── 收集 linked_files
│ ├── references/*.md
│ ├── templates/*.yaml
│ ├── scripts/*.py
│ └── assets/*
└── 返回 JSON：
{
"success": true,
"name": "skill-name",
"content": "侠游戏发布此文仅为了传递信息，不代表侠游戏网站认同其观点或证实其描述
同类更新
更多
热游推荐
更多-
- DreamStudio
- Android/ | AI绘图
- 2026-06-30
-
-
- Playground AI
- Android/ | AI绘图
- 2026-06-30
-
- Adobe Firefly
- Android/ | AI绘图
- 2026-06-30
-
-
-
- Leonardo AI
- Android/ | AI绘图
- 2026-06-30
-
- Stable Diffusion
- Android/ | AI绘图
- 2026-06-30
