Hermes Skill 开发实战教程：从零到部署

发布于 2026-05-12 15:28

Hermes Skill 开发实战教程：从零到部署

本文以"查询天气"为例，手把手教你如何开发、安装和验证 Hermes Skill。

一、Skill 是什么？

Hermes Skill 是一种可复用的程序性知识（procedural knowledge），用于：

  • 封装复杂任务的工作流
  • 记录最佳实践和避坑指南
  • 存储 API 端点、工具命令和验证步骤

Skill 与 Memory 的区别：

  • Memory：存储事实性信息（用户偏好、环境详情、工具特性）
  • Skill：存储流程性知识（工作步骤、命令序列、注意事项）

Skill 文件结构：

~/.hermes/skills/
├── your-skill/
│   ├── SKILL.md            # 主文件（必需）
│   ├── references/             # 参考资料（可选）
│   ├── templates/             # 模板文件（可选）
│   ├── scripts/               # 脚本（可选）
│   └── assets/                  # 静态资源（可选）

二、Step-by-Step：开发天气查询 Skill

Step 1：创建 Skill 目录结构

# 创建 skill 目录
mkdir -p ~/.hermes/skills/weather-query/{references,templates,scripts,assets}

# 进入目录
cd ~/.hermes/skills/weather-query

Step 2：编写 SKILL.md 主文件

SKILL.md 由两部分组成：

  1. YAML frontmatter（元数据）
  2. Markdown body（内容主体）

创建 SKILL.md：

---
name: weather-query
description: "查询指定城市的实时天气信息"
version: 1.0.0
author: Your Name
license: MIT
platforms: [linux, macos, windows]
metadata:
  tags: [weather, api, open-meteo]
---

# 天气查询 Skill

本 Skill 用于查询指定城市的实时天气信息，支持全球主要城市。

## 使用方法

当用户询问天气时，直接调用 `get_weather` 函数：
\`\`\`python
from hermes_tools import terminal
import json

def check_requirements():
    """检查必要的环境变量"""
    return True  # Open-Meteo API 无需 API key

def get_weather(city: str, country: str = "CN"):
    """查询城市天气
    
    Args:
        city: 城市名称（英文）
        country: 国家代码（默认 CN）
    
    Returns:
        JSON 格式的天气数据
    """
    # Open-Meteo API（免费，无需 API key）
    url = f"https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true"
    
    # 需要先获取城市的经纬度（可通过 geocoding API）
    # 这里使用简化的坐标映射
    coords = {
        "Beijing": (39.9042, 116.4074),
        "Shanghai": (31.2304, 121.4737),
        "Guangzhou": (23.1291, 113.2644),
        "Shenzhen": (22.5431, 114.0579),
        "New York": (40.7128, -74.0060),
        "London": (51.5074, -0.1278),
        "Tokyo": (35.6762, 139.6503),
        "Paris": (48.8566, 2.3522),
        "Sydney": (-33.8688, 151.2093),
    "Berlin": (52.5200, 13.4050),
    }
    
    lat, lon = coords.get(city, (0, 0))
    
    result = terminal(f"curl -s '{url}'")
    return result

# 注册到 Hermes 工具注册表
from tools.registry import registry

registry.register(
    name="get_weather",
    toolset="weather",
    schema={
        "name": "get_weather",
        "description": "查询城市实时天气",
        "parameters": {
            "city": {"type": "string", "description": "城市名称（英文）"},
            "country": {"type": "string", "description": "国家代码", "default": "CN"}
        }
    },
    handler=lambda args, **kw: get_weather(
        city=args.get("city", ""),
        country=kw.get("country", "CN")
    ),
    check_fn=check_requirements,
    requires_env=[],  # 无需环境变量
)
\`\`\`

将上述内容保存到 `~/.hermes/skills/weather-query/SKILL.md`

### Step 3：添加参考文档（可选）

创建 `references/usage.md`：

```markdown
# 使用示例

## 命令行调用
\`\`\`bash
# 查询北京天气
hermes chat -q "北京今天天气怎么样？"
\`\`\`\`

## API 端点
Open-Meteo API: https://open-meteo.com/en/docs

Step 4：添加模板文件（可选）

创建 templates/weather-report-template.md：

# 天气报告模板

**城市**: {{city}}
**温度**: {{temperature}}°C
**天气**: {{weather_code}}
**风速**: {{windspeed}} km/h
**湿度**: {{humidity}}%

三、安装 Skill

方法 1：通过 Skills Hub 安装

# 浏览可用 skills
hermes skills browse

# 搜索天气相关的 skill
hermes skills search weather

# 安装 skill（使用 Hub ID 或 GitHub URL）
hermes skills install weather-query

# 或者直接使用 GitHub URL 安装
hermes skills install https://github.com/your-repo/weather-query/SKILL.md

方法 2：手动安装

# 将 skill 目录复制到 ~/.hermes/skills/
cp -r weather-query ~/.hermes/skills/

方法 3：在会话中加载

# 启动 Hermes 时预加载 skill
hermes -s weather-query

# 或在会话中动态加载
/skill weather-query

四、验证 Skill

验证 1：检查 Skill 是否已安装

hermes skills list

输出示例：

✓ weather-query - 查询指定城市的实时天气信息

验证 2：在会话中测试 Skill

启动 Hermes：

hermes -s weather-query

在会话中提问：

You: 北京今天天气怎么样？
Hermes: [调用 get_weather 工具查询天气...]

验证 3：验证工具是否注册成功

# 在 Hermes CLI 中检查工具状态
hermes tools list

应该能看到 get_weather 工具。

验证 4：完整功能测试

# 单次查询测试
hermes chat -q "查询北京和上海的天气对比" -s weather-query

# 交互式测试
hermes -s weather-query
# 然后输入：北京今天天气怎么样？

预期输出：包含温度、天气状况等信息。

五、天气查询 Skill 完整示例

完整的 SKILL.md 内容：

---
name: weather-query
description: "查询指定城市的实时天气信息"
version: 1.0.0
author: Hermes Tutorial
license: MIT
platforms: [linux, macos, windows]
metadata:
  api: open-meteo
  tags: [weather, forecast, temperature]
---

# 天气查询 Skill

本 Skill 用于查询指定城市的实时天气信息，使用 Open-Meteo 免费 API。

## API 信息

- **端点**: https://api.open-meteo.com/v1/forecast
- **文档**: https://open-meteo.com/en/docs
- **认证**: 无需 API key

## 使用方法

当用户询问天气时，按以下步骤操作：

1. 识别用户询问的城市名称
2. 将城市名转换为经纬度坐标
3. 调用 Open-Meteo API 获取天气数据
4. 解析返回结果并格式化输出

## 支持的城市

- Beijing（北京）
- Shanghai（上海）
- Guangzhou（广州）
- Shenzhen（深圳）
- New York（纽约）
- London（伦敦）
- Tokyo（东京）
- Paris（巴黎）
- Sydney（悉尼）
- Berlin（柏林）
- 以及更多...

## 坐标映射

主要城市的经纬度已在代码中预定义。如需添加新城市，请更新 `coords` 字典。

## 错误处理

- 如果城市未找到，提示用户支持的城市列表
- API 超时或失败时，返回错误信息

## 示例输出

用户：北京今天天气怎么样？
Hermes：正在查询北京的天气...
查询结果：
- 温度: 25°C
- 天气: 晴
- 风速: 12 km/h
- 湿度: 45%

六、常见问题

Q1: Skill 文件修改后不生效？

A: 需要重启会话（/reset）或重新加载（/reload-skills）

Q2: 如何调试 Skill？

A: 查看日志：

tail -f ~/.hermes/logs/gateway.log

Q3: 如何发布 Skill 到 Hub？

A:

hermes skills publish ~/.hermes/skills/weather-query

七、总结

Hermes Skill 开发流程：

  1. 创建目录结构 → ~/.hermes/skills/<skill-name>/
  2. 编写 SKILL.md → YAML frontmatter + Markdown body
  3. 添加参考/模板/脚本（可选）
  4. 安装 Skill → hermes skills install 或手动复制
  5. 验证 Skill → hermes skills list + 实际测试
  6. 持续维护 → 根据使用反馈更新更新 Skill

最佳实践：

  • 保持 Skill 简洁明了
  • 包含清晰的错误处理
  • 提供使用示例
  • 记录常见问题

相关资源：

← 返回博客列表
文章信息

标题: Hermes Skill 开发实战教程：从零到部署

发布时间: 2026-05-12 15:28