# Hermes Agent 技能规范摘要

> 基于 Hermes Agent 官方文档和 GitHub 仓库（`nousresearch/hermes-agent`）整理。

## 文件结构

```
<skill-name>/
├── SKILL.md          # 核心指令文件（必填）
├── references/       # 按需加载的参考文档（可选）
├── templates/        # 模板文件（可选）
├── scripts/          # 辅助脚本（可选）
├── assets/           # 静态资源（可选）
└── CHANGELOG.md      # 版本变更记录（推荐）
```

## SKILL.md 规范

### YAML Frontmatter

文件必须以 `---` 开头（第一个字节），无空行或 BOM：

```yaml
---
name: my-skill-name              # 必填，≤64 字符，^[a-z][a-z0-9_-]*$
description: "Use when ..."      # 必填，≤1024 字符
version: 1.0.0                   # 推荐
author: <作者>                   # 推荐
license: MIT                     # 推荐
platforms: [linux, macos, windows]  # 推荐，不兼容平台自动隐藏
metadata:
  hermes:
    tags: [tag1, tag2]           # 推荐，搜索标签
    category: software-development  # 可选
    related_skills: [other-skill]  # 推荐，跨技能引用
    fallback_for_toolsets: []    # 可选，仅在特定工具缺失时显示
    requires_toolsets: []        # 可选，依赖的工具集
    config: []                   # 可选，配置项
---
```

### 验证器硬约束

| 约束 | 值 | 来源 |
|------|---|------|
| `name` 必填 | — | `skill_manager_tool.py::_validate_frontmatter` |
| `name` 最大长度 | 64 字符 | `MAX_NAME_LENGTH` |
| `description` 必填 | — | 同上 |
| `description` 最大长度 | 1024 字符 | `MAX_DESCRIPTION_LENGTH` |
| SKILL.md 最大长度 | 100,000 字符 | `MAX_SKILL_CONTENT_CHARS` |
| Frontmatter 开头 | `---`（第 0 字节） | 同上 |
| Frontmatter 闭合 | `\n---\n` | 同上 |
| Frontmatter 后正文 | 非空 | 同上 |

### 推荐正文结构

```markdown
# <标题>

## Overview
做什么，为什么。

## When to Use
- 触发条件
- "Don't use for:" 反触发

## <特定章节>
命令、表格、recipes...

## Common Pitfalls
编号列表。

## Verification Checklist
- [ ] 验证项
```

## 存放位置

| 类型 | 路径 | 创建方式 |
|------|------|---------|
| 用户本地 | `~/.hermes/skills/<name>/` | `skill_manage(action='create')` |
| 项目仓库 | `skills/<category>/<name>/` | `write_file` + `git add` |
| 外部导入 | `~/.hermes/skills/openclaw-imports/` | 从 OpenClaw 迁移 |

## 分类目录（官方）

```
autonomous-ai-agents  creative  data-science  devops  dogfood
email  gaming  github  leisure  mcp  media  mlops
note-taking  productivity  red-teaming  research
smart-home  social-media  software-development
```

选择最接近的已有分类，不要随意创建新分类。

## 渐进式披露

| 层级 | API | 内容 |
|------|-----|------|
| L0 | `skills_list()` | 基础元数据（name + description） |
| L1 | `skill_view(name)` | 完整 SKILL.md |
| L2 | `skill_view(name, path)` | 特定 references/ 文件 |

## Skill Bundles

多个技能可打包为一个 Bundle：

- 存放路径：`~/.hermes/skill-bundles/`
- 格式：YAML 文件
- 通过单个斜杠命令调用一组技能

## Skills Hub

- 官方 Hub：[agentskills.io](https://agentskills.io)
- 支持来源：`official`、`skills-sh`、`well-known`、`github`
- 所有第三方安装会经过安全扫描

## 编辑已有技能

| 操作 | 方法 |
|------|------|
| 小修复 | `skill_manage(action='patch', name=..., old_string=..., new_string=...)` |
| 大重写 | `write_file` 整个 SKILL.md |
| 添加辅助文件 | `write_file` 到 references/templates/scripts/assets |