自定义 Skills

教程概述

Skills 是 Hermes Agent 的能力扩展机制。通过编写自定义 Skill，你可以让 Agent 调用任意外部 API、操作本地文件、访问数据库。本教程带你从 0 到 1 编写第一个 Skill，并介绍 Skills 的发布与组合策略。

前提条件

开始前请确认满足以下条件

已完成「基础配置」教程
熟悉 TypeScript 或 JavaScript
了解 JSON Schema 与函数调用（function calling）

学习目标

完成本教程后你将能够

理解 Skill 的生命周期与工作原理
编写一个完整可运行的 Skill
在 Agent 中注册并使用 Skill
学习多个 Skill 协作的设计模式

详细步骤

1
认识 Skill 的结构
每个 Skill 都包含三部分：metadata（描述）、parameters（入参 schema）、handler（实现逻辑）。
text
```
skills/weather/
├── manifest.json   # Skill 元数据
├── schema.json     # 参数定义
└── handler.ts      # 业务逻辑
```

定义 Skill 元数据

manifest 用于让 Agent 理解何时该调用此 Skill，描述要清晰、具体。

json

{
  "name": "get_weather",
  "version": "1.0.0",
  "description": "根据城市名查询当前天气，返回温度、湿度、风力等信息。"
}

定义参数 Schema

使用 JSON Schema 描述入参，Agent 会据此自动校验并补全字段。

json

{
  "type": "object",
  "properties": {
    "city": { "type": "string", "description": "城市名称，如 北京" },
    "unit": { "type": "string", "enum": ["c", "f"], "default": "c" }
  },
  "required": ["city"]
}

小贴士：字段描述越详细，模型生成的调用参数越准确。

实现 handler

handler 接受参数并返回结果，Hermes Agent 会自动把结果回填到对话中。

typescript

import { defineSkill } from "@hermes/skills";

export default defineSkill(async ({ city, unit }) => {
  const res = await fetch(`https://api.weather.com/v1/now?city=${city}`);
  const data = await res.json();
  return {
    city,
    temp: unit === "f" ? data.tempF : data.tempC,
    humidity: data.humidity,
    wind: data.wind,
  };
});

5
注册 Skill 到 Agent
在 config/skills.json 中加入新的 Skill 路径，重启后生效。
json
```
{
  "enabled": ["weather", "calculator", "web_search"]
}
```
6
测试与调试
向 Agent 询问 “今天上海多少度？”，观察控制台是否打印调用日志，并确认返回内容正确。
bash
```
DEBUG=hermes:skills npm run dev
```
注意：上线前务必为 Skill 加上超时与异常兜底，避免拖垮整个 Agent。
7
组合多个 Skill
Agent 可以在同一轮对话中调用多个 Skill。例如 “搜索今日新闻并发到飞书” 会先用 web_search 再用 feishu_send。

最佳实践

Skill 描述要写清楚 “何时使用”，避免模型乱调用
为每个 Skill 编写单元测试，覆盖正常与异常路径
把外部依赖（API、数据库）封装在 Skill 内部，保持 Agent 主流程纯净
通过 agentskills.io 等社区平台分享和复用 Skill

常见问题

Q1.Agent 总是不调用我的 Skill？

请检查 description 是否描述清晰，或者提高系统提示词中对该能力的引导。

Q2.Skill 的执行时间过长怎么办？

建议设置 timeout 并在 handler 内部使用流式返回，分阶段反馈进度。

Q3.如何让 Skill 访问私有数据库？

在 .env 中配置数据库连接，并在 handler 中使用对应 SDK；务必做参数校验。

🎉 教程总结

至此你已完整走过 Hermes Agent 的入门旅程：启动 → 配置 → 集成 → 扩展。建议继续阅读「记忆架构」与「实战案例」，了解如何让 Agent 拥有长期记忆与具体业务能力。