第二章 Skills 开发

Skill 是 Hermes Agent 最主要的扩展方式。不需要改源码，不需要写 Python 类，只要一个 Markdown 文件就能教墨鱼新技能。

Skill vs Tool：选哪个？

	Skill	Tool (插件)
形式	Markdown 文档	Python 代码
修改源码	不需要	需要
开发难度	低	中-高
适用场景	工作流指导、API 集成	新工具类型、底层能力
分享方式	Skills Hub / GitHub	PR 到主仓库

经验法则：90% 的需求用 Skill 就能解决。只有当你需要注册全新的工具类型时，才考虑 Tool 插件。

---

目录结构

~/.hermes/skills/
└── my-skill/
    ├── SKILL.md              # 必需：技能指令
    ├── references/           # 可选：参考文档
    │   └── api-reference.md
    ├── templates/            # 可选：模板文件
    │   └── config.yaml
    ├── scripts/              # 可选：辅助脚本
    │   └── helper.py
    └── assets/               # 可选：资源文件

官方 Skills 按类别组织在 skills/ 下：

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md
│       └── scripts/search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       └── references/
└── ...

---

SKILL.md 完整格式

---
name: my-skill
description: 一句话描述技能用途（搜索结果中显示）
version: 1.0.0
author: Your Name
license: MIT

# 平台限制（可选）
platforms: [macos, linux]

metadata:
  hermes:
    tags: [分类, 子分类, 关键词]
    related_skills: [other-skill]

    # 条件激活
    requires_toolsets: [web]           # 仅当 web 工具集可用时显示
    requires_tools: [web_search]       # 仅当 web_search 工具可用时显示
    fallback_for_toolsets: [browser]   # 当 browser 工具集不可用时作为回退
    fallback_for_tools: [browser_navigate]

    # 非密钥配置
    config:
      - key: my.setting
        description: "配置说明"
        default: "sensible-default"
        prompt: "配置提示语"

# 环境变量（密钥）
required_environment_variables:
  - name: MY_API_KEY
    prompt: "输入你的 API Key"
    help: "在 https://example.com 获取"
    required_for: "API 访问功能"
---

# 技能标题

简短介绍。

## 何时使用

触发条件——Agent 什么时候该加载这个技能？

## 快速参考

常用命令或 API 调用速查表。

## 操作步骤

Agent 遵循的分步指令。

## 注意事项

已知失败模式和应对方法。

## 验证方法

Agent 如何确认操作成功。

---

Frontmatter 字段详解

基础字段

字段	必需	说明
name	✅	技能标识，小写+连字符
description	✅	搜索结果中的描述
version	❌	语义化版本号
author	❌	作者名
license	❌	开源协议

平台限制

platforms: [macos]          # 仅 macOS
platforms: [macos, linux]   # macOS + Linux
platforms: [windows]        # 仅 Windows
# 省略 → 所有平台

不兼容平台上的技能会自动从系统提示、技能列表和斜杠命令中隐藏。

条件激活

metadata:
  hermes:
    requires_toolsets: [web]              # 需要这些工具集才显示
    requires_tools: [web_search]          # 需要这些工具才显示
    fallback_for_toolsets: [browser]      # 当这些工具集不可用时才显示
    fallback_for_tools: [browser_navigate] # 当这些工具不可用时才显示

逻辑规则：

字段	隐藏条件
requires_toolsets	任一列出的 toolset 不可用
requires_tools	任一列出的 tool 不可用
fallback_for_toolsets	任一列出的 toolset 可用
fallback_for_tools	任一列出的 tool 可用

环境变量（密钥）

required_environment_variables:
  - name: MY_API_KEY
    prompt: "输入你的 API Key"
    help: "在 https://example.com 获取"
    required_for: "API 访问"

加载时自动处理：

• 本地 CLI：安全提示输入（不暴露给模型）
• Gateway/聊天：显示本地设置指引
• 自动传入 execute_code 和 terminal 沙箱

配置项（非密钥）

metadata:
  hermes:
    config:
      - key: output_dir
        description: "输出目录"
        default: "~/output"
        prompt: "设置输出目录"

存储在 config.yaml 的 skills.config 下，加载时自动注入到 Agent 上下文。

---

编写最佳实践

1. 渐进式披露

把最常用的流程放在最前面，边缘情况和高级用法放底部：

## 快速开始（90% 场景用这个）
...

## 高级用法
...

## 故障排除
...

这样可以节省 Token，常见任务只加载前半部分。

2. 不依赖外部包

优先使用：

• Python 标准库
• curl（已内置）
• Hermes 现有工具（web_extract, terminal, read_file）

如果必须用外部依赖，在技能中明确说明安装步骤。

3. 包含辅助脚本

复杂的解析逻辑放在 scripts/ 目录，不要让 LLM 每次都重新写：

scripts/
└── parse_api_response.py   # 解析 API 响应的辅助脚本

4. 包含验证步骤

让 Agent 知道如何确认操作成功：

## 验证

执行以下命令确认配置生效：
\`\`\`bash
hermes doctor
\`\`\`
如果输出包含 "✅ my-service: connected"，说明配置成功。

---

实战：创建一个自定义 Skill

场景

创建一个 git-workflow 技能，帮助 Agent 管理 Git 分支和 PR。

步骤 1：创建目录

mkdir -p ~/.hermes/skills/git-workflow

步骤 2：编写 SKILL.md

---
name: git-workflow
description: Git 分支管理和 PR 工作流
metadata:
  hermes:
    tags: [git, workflow, github]
    related_skills: [github-pr-workflow]
---

# Git Workflow

管理 Git 分支、提交和 PR 的工作流技能。

## 何时使用

用户提到以下关键词时加载：
- 创建分支 / 新功能分支
- 提交代码 / commit
- 创建 PR / 发起合并

## 分支命名规范

- 功能分支：feature/xxx
- 修复分支：fix/xxx
- 发布分支：release/vX.Y.Z

## 操作流程

### 创建功能分支

1. 从 main 拉取最新代码
2. 创建 feature/xxx 分支
3. 开发完成后提交
4. 推送并创建 PR

### 提交信息规范

格式：type(scope): description

type 包括：feat, fix, docs, refactor, test, chore

## 注意事项

- 永远不要直接推送到 main
- PR 描述要包含变更说明和测试步骤
- 合并前确保 CI 通过

步骤 3：测试

你：帮我创建一个新功能分支
Hermes：[自动加载 git-workflow 技能]
        好的，新功能的名称是什么？

步骤 4：迭代优化

根据实际使用体验，修改 SKILL.md 的措辞和步骤，直到 Agent 表现满意。

---

发布技能

发布到 Skills Hub

hermes skills publish my-skill

所有 Hub 安装的技能会经过安全扫描，检查：

• 恶意命令注入
• 敏感信息泄露
• 不安全的文件操作

发布到自定义仓库

1. 创建 GitHub 仓库存放技能
2. 用户添加为 tap：

hermes skills tap add your-username/your-skills-repo
hermes skills install my-skill

内置到官方

如果你的技能足够通用，可以提 PR 到 Hermes Agent 主仓库：

• 通用技能 → skills/ 目录
• 有特定依赖的 → optional-skills/ 目录

---

技能放置位置对比

位置	适合	安装方式
~/.hermes/skills/	个人/自定义技能	手动创建
Skills Hub	社区共享技能	hermes skills install
GitHub tap	团队/组织技能	hermes skills tap add
源码 skills/	官方内置技能	随 Hermes 安装
源码 optional-skills/	官方可选技能	hermes skills browse

深入阅读

• 官方 Creating Skills 文档
• Skills Hub
• 第6章 技能系统

---