Hermes Agent Skills：3 级渐进加载 × 6 步调度 × 5 维安全扫描，让 Agent 学会积累经验

Hermes Agent Skills：3 级渐进加载 × 6 步调度 × 5 维安全扫描，让 Agent 学会积累经验

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 122 篇，Hermes Agent 最佳实战「2026」系列第 4 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

封面图

图 1：Hermes Agent Skills System 核心概念

说明：本文内容基于 Hermes Agent 源码（NousResearch/hermes-agent）和官方文档分析整理而成，源码分析基于笔者本地仓库版本。文中的配置模板和参数建议仅供参考，实际效果请以你的业务数据和环境测试结果为准。如果有实际使用经验，欢迎在评论区分享交流。

用 AI Agent 做过复杂任务的人大概都有这个体会：推理能力不差，但每次开新会话，之前踩过的坑、摸索出的方案，全都得重来一遍。

这不是个别现象。AI Agent 普遍存在一个结构性问题——记忆太短。模型本身的能力在飞速迭代，但 Agent 层面的经验沉淀机制一直很薄弱。翻了一圈社区讨论，发现这个痛点出奇一致：Agent 的核心短板不是推理能力，是记不住教训。

Hermes Agent 的 Skills System 试图从架构层面解决这件事。思路很明确：把 Agent 的经验沉淀为可复用的指令文档（Skills），让 Agent 具备真正的过程性记忆。这篇文章我就从源码和官方文档出发，拆解这套系统的设计逻辑和实操方法。

1. Skills 到底是什么

Skills 在 Hermes Agent 架构中的定位

图 2：通用记忆 vs 过程性记忆——Skills 在 Hermes Agent 记忆体系中的定位

要理解 Skills，先得搞清楚它在 Hermes Agent 记忆体系中的位置。

Hermes 有两套记忆机制。一套是通用记忆（MEMORY.md、USER.md），存储知道什么——比如用户偏好 Python、项目用了 React。另一套是 Skills，属于过程性记忆（Procedural Memory），存储怎么做——比如怎么用 Axolotl 微调一个 Llama 模型、怎么走完一个完整的 K8s 部署流程。

这个区分很关键。通用记忆告诉你用户喜欢 Python，但不会教你从头到尾搭建一个 Python 项目需要几步。Skills 填的就是这个缺——窄域、可执行的指令文档，每个 Skill 专注解决某一类特定任务。

有意思的是，Skills 遵循 agentskills.io 开放标准（https://agentskills.io/specification），不是 Hermes 自己搞的私有格式。你写好的 Skill 理论上能在其他兼容这个标准的 Agent 上跑。

2. 渐进式披露：核心设计哲学

Skills System 的核心设计用四个字概括：渐进式披露（Progressive Disclosure）。

翻开源码（tools/skills_tool.py），可以看到加载分三个层级：

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata       (varies)
Level 2: skill_view(name, path)  → Specific reference file       (varies)

Level 0 只加载元数据列表，大约 3k tokens。Agent 先扫一遍这个列表，判断哪些 Skill 和当前任务相关，然后才调用 skill_view() 拉取完整内容。

为什么要这么设计？Agent 可能装了几十个 Skills。如果每次对话都把所有 Skill 全文塞进上下文，token 消耗会非常夸张。渐进式披露让 Agent 按需加载，只在真正需要时才花 token。

这和代码里的懒加载是一个思路——用到再加载，不用就别占内存。从工程角度看，这个设计简洁且有效。

3. 从源码看调度与激活

斜杠命令调度流程

图 3：Skill 斜杠命令 6 步调度流程

每个安装好的 Skill 自动注册为斜杠命令。用法像这样：

/axolotl help me fine-tune Llama 3
/plan design a rollout for migrating our auth provider

查看 agent/skill_commands.py 的调度逻辑，整个流程分六步：

1. 解析斜杠命令，提取 Skill 名称和用户指令
2. 调用 skill_view() 加载完整 Skill 内容
3. 执行模板变量替换（${HERMES_SKILL_DIR}、${HERMES_SESSION_ID}）
4. 可选执行内联 Shell 片段（默认关闭）
5. 注入 Skill 目录信息和配置值
6. 组装为用户消息发送给 Agent

步骤 3 和 4 值得展开说说。模板变量替换是默认开启的，比如 Skill 里写 ${HERMES_SKILL_DIR}，运行时会被替换为 Skill 目录的绝对路径。内联 Shell 执行默认关闭，需要在 config.yaml 手动开启——安全考量，合理。

条件激活的精巧设计

条件激活是这套系统里设计得比较精巧的部分。通过 frontmatter 里的四个字段，可以让 Skill 根据当前会话的工具可用性自动显示或隐藏：

内置的 duckduckgo-search 技能用了 fallback_for_toolsets: [web]。当用户配了 FIRECRAWL_API_KEY 时，web toolset 可用，DuckDuckGo 自动隐藏；没配时才作为降级方案显示出来。

这个设计的巧妙之处在于：Agent 不需要在系统提示里堆一堆 如果有 web toolset 就用 web search，没有就用 DuckDuckGo 的条件判断，Skills System 自动处理了适配问题。

4. 实战：从零创建一个 Skill

SKILL.md 文件结构

图 4：SKILL.md 文件结构——Frontmatter 字段 + Body 推荐段落

Frontmatter：必须搞对的元数据

SKILL.md 的 frontmatter 有必填和可选字段。根据源码整理完整结构：

---
name: my-skill                          # 必填，≤64字符，小写+数字+连字符
description: Brief description          # 必填，≤1024字符
version: 1.0.0                          # 可选
author: Your Name                       # 可选
license: MIT                            # 可选
platforms: [macos, linux]               # 可选：支持的平台
metadata:
  hermes:
    tags: [tag1, tag2]                  # 可选：标签
    category: devops                    # 可选：分类
    requires_toolsets: [terminal]       # 可选：条件激活
    fallback_for_toolsets: [web]        # 可选：降级方案
    config:                             # 可选：用户可配参数
      - key: my.setting
        description: "说明"
        default: "value"
---

源码里 _validate_frontmatter()（tools/skill_manager_tool.py）的校验比较严格，几个容易踩的硬约束：

• 文件必须以 --- 开头，前面不能有空行或 BOM
• 闭合的 --- 前后必须有换行
• Frontmatter 必须解析为合法的 YAML mapping
• name 和 description 必填
• Body 不能为空
• 总大小不超过 100,000 字符（约 36k tokens）

Body：推荐的文档结构

官方推荐的 Body 包含六个段落：

# Skill Title

## Overview
一两段概述，说清楚做什么。

## When to Use
触发条件列表，告诉 Agent 什么时候该用。

## Quick Reference
常用命令或 API 速查表。

## Procedure
具体的操作步骤。

## Pitfalls
已知故障模式和解决方案。

## Verification
确认操作成功的检查清单。

同侪技能（官方 skills/software-development/ 目录）的大小在 8-14k 字符。超过 20k 应该拆到 references/*.md 里，通过 skill_view(name, path) 按需加载——又回到渐进式披露的思路了。

两种创建方式

方式一：让 Agent 自己创建

Agent 通过 skill_manage 工具自主创建，触发时机挺有意思：

• 成功完成复杂任务（5+ 工具调用）后
• 走弯路后找到正确路径时
• 用户纠正其方法时
• 发现非平凡工作流时

patch 比 edit 更省 token——只替换需要改的部分，不重写整个文件。和 git diff 的道理一样。

方式二：手动创建

直接在 ~/.hermes/skills/<category>/<name>/SKILL.md 路径下创建文件，或者在仓库的 skills/<category>/ 目录下创建后 git add + git commit。

你在项目中用过类似的 Agent 技能复用方案吗？欢迎在评论区聊聊。

5. 进阶：Bundle、模板变量与外部目录

Bundle：把多个 Skill 打包

一组经常一起用的 Skill，可以打成一个 Bundle：

# ~/.hermes/skill-bundles/backend-dev.yaml
name: backend-dev
description: Backend feature work - review, test, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests, then implement.

使用时 /backend-dev 一条命令激活三个 Skill。有个细节：Bundle 和 Skill 同名时，Bundle 优先。这暗示 Bundle 的定位是编排层，不是简单的别名。

管理命令：

hermes bundles create backend-dev --skill github-code-review --skill test-driven-development
hermes bundles list
hermes bundles delete backend-dev

内联 Shell：在 Skill 里嵌入动态内容

模板变量默认开启，支持两个内置变量：

• ${HERMES_SKILL_DIR} → Skill 目录的绝对路径
• ${HERMES_SESSION_ID} → 当前会话 ID

内联 Shell 执行默认关闭，需要手动开启：

# config.yaml
skills:
  inline_shell: true
  inline_shell_timeout: 10   # 每个片段超时秒数

开启后可以在 SKILL.md 里嵌入动态内容：

当前日期：!`date -u +%Y-%m-%d`
Git 分支：!`git -C ${HERMES_SKILL_DIR} rev-parse --abbrev-ref HEAD`

输出上限 4000 字符，失败返回 [inline-shell error: ...] 标记。说实话，这个功能实用，但默认关闭是对的——在 SKILL.md 里执行任意 Shell 命令，安全风险不小。

外部 Skill 目录：多工具共享

想让多个 AI 工具共享同一套 Skills？配置外部目录就行：

# config.yaml
skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills

优先级：本地 ~/.hermes/skills/ 优先。外部目录可写时 Agent 可以就地修改。

6. 安全扫描与分发生态

安全扫描流程

图 5：Skills Hub 安装流程 + 五维安全扫描 + 四档信任等级分层

Skills Guard：五维安全扫描

所有从 Hub 安装的第三方 Skill 都会经过安全扫描器（tools/skills_guard.py），覆盖五个维度：

• 数据泄露：curl/wget 泄露环境变量、SSH/AWS 目录访问
• 提示注入：ignore previous instructions、角色劫持
• 破坏性命令：rm -rf /、fork bomb
• 持久化后门：crontab、启动项
• 网络监听：nc -l、socat 等反向 Shell 模式

还会检测 base64 编码的混淆命令——说明扫描器的设计者确实考虑过真实攻击场景。

信任等级分四档：

这个分层模型和浏览器 SSL 证书信任链的思路类似——内置的默认信任，社区的加强审核。

Skills Hub：六种分发来源

Hermes 集成了多个 Skills 生态：

日常操作命令：

hermes skills browse                              # 浏览
hermes skills search react --source skills-sh     # 搜索
hermes skills install openai/skills/k8s           # 安装
hermes skills check                               # 检查更新
hermes skills update                              # 更新

还支持自定义 Tap（私有 Skill 仓库）：

hermes skills tap add myorg/skills-repo
hermes skills install myorg/skills-repo/deploy-runbook

7. 避坑指南

整理调研素材时，发现几个容易踩的坑：

坑一：Frontmatter 格式不通过

_validate_frontmatter() 校验严格。常见错误：文件开头有空行或 BOM、闭合 --- 前后缺换行、YAML 语法错误。建议创建后先跑一遍验证。

坑二：Skill 文件太大塞满上下文

官方同侪技能在 8-14k 字符。超过 20k 的应该拆到 references/*.md 里，按需加载。全塞进主文件，每次加载都浪费 token。

坑三：条件激活字段逻辑搞反

fallback_for_toolsets 是当列出的 toolset 可用时隐藏，不是当可用时显示。命名确实容易搞混。建议写完后在有无对应 toolset 的两种环境下都测试。

坑四：支撑文件路径越界

write_file 添加的文件路径限制在 references/、templates/、scripts/、assets/ 四个子目录内。单文件上限 1 MiB。

坑五：用 edit 替代 patch

更新 Skill 时，除非做大幅结构重写，否则优先用 patch（指定 old_string → new_string）。edit 替换整个文件，token 消耗远大于 patch。

总结

说到底，Skills System 解决的是 AI Agent 经验无法积累的问题。通过把怎么做抽象为可复用的指令文档，配合渐进式披露按需加载、条件激活自动适配、安全扫描保障信任、Hub 生态实现分发，形成了一套相对完整的过程性记忆方案。

有一个设计决策值得琢磨：Skill 和 Tool 的边界在哪？

Skill 轻量灵活，分发只需要一个文件；Tool 能力更强，但代价也更大。这个取舍和微服务架构里轻量脚本 vs 重量服务的决策逻辑异曲同工。

如果你正在设计自己的 Agent 系统，Skills 的架构思路值得参考。渐进式披露解决 token 效率、条件激活解决运行时适配、分层信任解决安全保障——三个设计点可以独立使用，不一定非要整体搬过去。

如果你对 Agent 架构设计有自己的思考，欢迎在评论区聊聊，也方便我把大家关心的问题整理成后续内容。

相关资源

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/skills

GitHub 仓库：https://github.com/NousResearch/hermes-agent

agentskills.io 规范：https://agentskills.io/specification

创建 Skills 开发者指南：https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！