Skill 执行过程详解
·
本文档详细描述 Hermes Agent 中 Skill 的完整执行流程，包括发现、加载、安全检查、环境变量处理、提示词构建等各个环节。
目录
概述
Skill 是 Hermes Agent 的可扩展指令系统，允许用户通过 /skill-name 命令调用预定义的任务模板。Skill 以 Markdown 文件形式存储，包含 YAML frontmatter 元数据和指令正文。
核心流程：
发现 → 加载 → 安全检查 → 环境检查 → 消息构建 → 注入上下文 → Agent 执行
核心文件职责
| 文件 | 职责 |
|---|---|
agent/skill_utils.py |
轻量级元数据工具（解析、平台检查、禁用列表），无重依赖 |
agent/skill_commands.py |
Slash 命令处理、消息构建、预加载 |
tools/skills_tool.py |
核心 skill 加载、查看、环境检查、安全验证 |
tools/skills_hub.py |
Hub 管理、远程 skill 安装 |
执行阶段详解
阶段 1: Skill 发现与扫描
入口函数: scan_skill_commands() (agent/skill_commands.py:223)
扫描流程:
┌─────────────────────────────────────────────────────────────┐
│ 1. 获取 skills 目录列表 │
│ - 本地目录: ~/.hermes/skills/ │
│ - 外部目录: config.yaml 中的 skills.external_dirs │
│ │
│ 2. 递归查找所有 SKILL.md 文件 │
│ - 排除 .git, .github, .hub 目录 │
│ │
│ 3. 解析 YAML frontmatter │
│ - 使用 parse_frontmatter() 解析元数据 │
│ │
│ 4. 过滤检查 │
│ ✓ 平台兼容性: skill_matches_platform() │
│ ✓ 禁用状态: _get_disabled_skill_names() │
│ ✓ 名称去重 │
│ │
│ 5. 构建命令映射 │
│ "/skill-name" → {name, description, path, dir} │
└─────────────────────────────────────────────────────────────┘
关键函数:
parse_frontmatter()- 解析 YAML frontmatterskill_matches_platform()- 检查平台兼容性get_disabled_skill_names()- 获取禁用的 skill 列表get_external_skills_dirs()- 获取外部 skills 目录
阶段 2: Skill 加载
入口函数: _load_skill_payload() (agent/skill_commands.py:55)
加载流程:
┌─────────────────────────────────────────────────────────────┐
│ 1. 标识符规范化 │
│ - 处理绝对路径/相对路径 │
│ - 去除前导斜杠 │
│ │
│ 2. 调用 skill_view() 加载 skill 内容 │
│ → 进入 skills_tool.py 的核心加载逻辑 │
│ │
│ 3. 返回加载结果 │
│ (loaded_skill dict, skill_dir Path, skill_name str) │
└─────────────────────────────────────────────────────────────┘
阶段 3: Skill 查看核心逻辑
核心函数: skill_view() (tools/skills_tool.py:788)
skill_view() 详细流程:
┌─────────────────────────────────────────────────────────────┐
│ 阶段 A: 路径解析 │
│ 1. 搜索所有 skills 目录（本地优先，然后外部） │
│ 2. 尝试三种匹配方式: │
│ - 直接路径匹配: "mlops/axolotl" │
│ - 目录名匹配: 遍历查找 parent.name == name │
│ - 遗留扁平 .md 文件匹配 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段 B: 安全检查 │
│ 1. 路径遍历攻击检测 (.. 检查) │
│ 2. 目录边界验证 │
│ 3. Prompt 注入模式检测 │
│ 4. 平台兼容性检查 │
│ 5. 禁用状态检查 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段 C: 环境变量检查 │
│ 1. 收集 required_environment_variables │
│ 2. 收集 setup.collect_secrets │
│ 3. 收集遗留 prerequisites.env_vars │
│ 4. 检查环境变量是否已设置 │
│ 5. 如有缺失，触发捕获回调 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段 D: 收集关联文件 │
│ 1. references/ - 参考文档 │
│ 2. templates/ - 模板文件 │
│ 3. assets/ - 资源文件 │
│ 4. scripts/ - 脚本文件 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 阶段 E: 构建返回结果 │
│ 返回包含 success, name, content, setup_needed 等字段的字典 │
└─────────────────────────────────────────────────────────────┘
阶段 4: Skill 消息构建
核心函数: _build_skill_message() (agent/skill_commands.py:121)
消息构建流程:
┌─────────────────────────────────────────────────────────────┐
│ 1. 添加激活提示 │
│ 2. 添加 SKILL.md 完整内容 │
│ 3. 注入配置值（如有） │
│ 4. 添加 setup 提示（如有） │
│ 5. 添加关联文件提示（如有） │
│ 6. 添加用户指令（如有） │
└─────────────────────────────────────────────────────────────┘
阶段 5: Skill 执行入口
方式 A: Slash 命令调用
用户输入: /skill-name [instruction]
↓
gateway/run.py 或 cli.py 捕获命令
↓
resolve_skill_command_key() 解析命令
↓
build_skill_invocation_message() 构建消息
↓
将消息注入到对话上下文中
↓
Agent 根据 skill 指令执行任务
方式 B: CLI 预加载
hermes --skill skill-name
↓
build_preloaded_skills_prompt() 加载
↓
将 skill 内容添加到系统提示中
↓
整个会话期间 skill 指令生效
SKILL.md 文件结构
基本结构
---
name: skill-name # 必需，≤64 字符
description: Brief description # 必需，≤1024 字符
version: 1.0.0 # 可选
platforms: [macos, linux] # 可选，平台限制
metadata:
hermes:
tags: [tag1, tag2]
related_skills: [other-skill]
config:
- key: wiki.path
description: Wiki path
default: "~/wiki"
---
# Skill Title
Skill 正文内容...
外部接口声明
方式 A: required_environment_variables（推荐）
required_environment_variables:
- name: API_KEY
prompt: Enter your API key
help: "Get it from https://example.com/settings"
方式 B: setup.collect_secrets
setup:
collect_secrets:
- env_var: OPENAI_API_KEY
prompt: Enter your OpenAI API key
provider_url: https://platform.openai.com/api-keys
方式 C: 遗留 prerequisites.env_vars
prerequisites:
env_vars: [API_KEY]
commands: [curl, jq]
方式 D: 凭证文件
required_credential_files:
- ~/.config/gcloud/application_default_credentials.json
提示词构建机制
构建公式
最终提示词 =
激活提示
+ SKILL.md 正文内容
+ 配置注入块（如有）
+ Setup 提示（如有）
+ 关联文件提示（如有）
+ 用户指令（如有）
各部分详解
Part 1: 激活提示
[SYSTEM: The user has invoked the "skill-name" skill, indicating they want you to follow its instructions. The full skill content is loaded below.]
Part 2: SKILL.md 正文
完整 Markdown 正文内容。
Part 3: 配置注入块（可选）
[Skill config (from ~/.hermes/config.yaml):
wiki.path = /Users/xxx/wiki
]
Part 4: Setup 提示（可选）
| 条件 | 提示内容 |
|---|---|
setup_skipped=True |
[Skill setup note: Required environment setup was skipped...] |
gateway_setup_hint |
[Skill setup note: {gateway_setup_hint}] |
setup_needed=True |
[Skill setup note: {setup_note}] |
Part 5: 关联文件提示（可选）
[This skill has supporting files you can load with the skill_view tool:
- references/api.md
To view any of these, use: skill_view(name="skill-name", file_path="<path>")]
Part 6: 用户指令（可选）
The user has provided the following instruction alongside the skill invocation: 用户指令
外部接口调用处理
环境变量检查流程
解析 frontmatter
│
├── 收集 required_environment_variables
├── 收集 setup.collect_secrets
└── 收集 prerequisites.env_vars
│
▼
检查环境变量是否已设置
│
├── ~/.hermes/.env 文件
└── 系统环境变量
│
▼
缺失时的处理:
├── CLI: 弹出交互式输入
└── Gateway: 返回提示信息
环境变量透传机制
已设置的环境变量会自动注册到沙箱执行环境，Agent 在 execute_code 或 terminal 中执行代码时可自动使用。
完整提示词示例
以 siyuan skill 为例，用户执行：/siyuan 在我的笔记中搜索"项目计划"
场景 A：环境变量完整
[SYSTEM: The user has invoked the "siyuan" skill, indicating they want you to follow its instructions. The full skill content is loaded below.]
# SiYuan Note API
Use the SiYuan kernel API via curl to search, read, create, update, and delete blocks and documents...
## API Basics
All SiYuan API calls are POST with JSON body...
## Quick Reference
| Operation | Endpoint |
|-----------|----------|
| Full-text search | `/api/search/fullTextSearchBlock` |
...
The user has provided the following instruction alongside the skill invocation: 在我的笔记中搜索"项目计划"
场景 B：环境变量缺失
[SYSTEM: The user has invoked the "siyuan" skill...]
# SiYuan Note API
...
[Skill setup note: Setup needed before using this skill: missing env $SIYUAN_TOKEN. Settings > About in SiYuan desktop app]
The user has provided the following instruction alongside the skill invocation: 在我的笔记中搜索"项目计划"
场景 C：用户跳过设置
[SYSTEM: The user has invoked the "siyuan" skill...]
# SiYuan Note API
...
[Skill setup note: Required environment setup was skipped. Continue loading the skill and explain any reduced functionality if it matters.]
The user has provided the following instruction alongside the skill invocation: 在我的笔记中搜索"项目计划"
场景 D：Gateway 环境
[SYSTEM: The user has invoked the "siyuan" skill...]
# SiYuan Note API
...
[Skill setup note: Secure secret entry is not available. Load this skill in the local CLI to be prompted, or add the key to ~/.hermes/.env manually.]
The user has provided the following instruction alongside the skill invocation: 在我的笔记中搜索"项目计划"
数据流图
用户输入: /skill-name [instruction]
│
▼
scan_skill_commands()
│
▼
_load_skill_payload()
│
▼
skill_view()
│
┌───────────┼───────────┐
│ │ │
路径解析 安全检查 环境变量检查
│ │ │
└───────────┼───────────┘
│
▼
_build_skill_message()
│
┌───────────┼───────────┐
│ │ │
激活提示 SKILL正文 Setup提示
│ │ │
└───────────┼───────────┘
│
▼
最终提示词
│
▼
注入到 Agent 上下文
│
▼
Agent 执行任务
关键代码位置
| 功能 | 文件:行号 |
|---|---|
| 解析 frontmatter | agent/skill_utils.py:46 |
| 平台兼容性检查 | agent/skill_utils.py:85 |
| 禁用列表获取 | agent/skill_utils.py:111 |
| 加载 skill payload | agent/skill_commands.py:55 |
| 构建消息 | agent/skill_commands.py:121 |
| skill_view 核心 | tools/skills_tool.py:788 |
| 环境变量收集 | tools/skills_tool.py:209 |
| 环境变量捕获 | tools/skills_tool.py:275 |
| 结果构建 | tools/skills_tool.py:1203 |
小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用
更多推荐
17
0- 0
已为社区贡献1条内容
所有评论(0)