# 如何创建 Hermes Agent 技能

本技能指导你为 Hermes Agent 框架创建符合规范的技能，基于官方文档和 GitHub 仓库中的最佳实践。

## 核心概念

Hermes Agent 技能（Skill）是代理的**程序化记忆**（Procedural Memory），代理在运行时创建和复用。技能遵循 [agentskills.io](https://agentskills.io) 开放标准，可跨平台共享。

## 技能存放位置

| 位置 | 路径 | 用途 |
|------|------|------|
| **用户本地** | `~/.hermes/skills/<name>/SKILL.md` | 个人技能，不共享，通过 `skill_manage(action='create')` 创建 |
| **项目仓库内** | `skills/<category>/<name>/SKILL.md` | 随项目提交，团队共享 |

## 创建流程

### 1. 调研已有技能

```bash
# 查看目标分类下已有的技能
ls skills/<category>/
```

阅读 2-3 个同类技能的 SKILL.md，匹配风格和结构。避免创建重复技能。

### 2. 创建 SKILL.md

文件必须：
- 以 `---` 开头（不能有空行或 BOM）
- YAML frontmatter 以 `\n---\n` 闭合
- frontmatter 后紧跟 Markdown 正文

### 3. 编写 Frontmatter

```yaml
---
name: my-skill-name               # 小写+连字符，≤64 字符
description: "Use when <触发条件>. <一句话行为描述>."  # ≤1024 字符
version: 1.0.0
author: <作者名>
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [短, 描述性, 标签]
    related_skills: [other-skill, another-skill]
---
```

**必填字段**（验证器强制）：
- `name`：≤64 字符，正则 `^[a-z][a-z0-9_-]*$`
- `description`：≤1024 字符，以 "Use when ..." 开头

**推荐字段**（所有官方技能都包含）：
- `version`、`author`、`license`、`platforms`
- `metadata.hermes.tags`、`metadata.hermes.related_skills`

### 4. 编写正文结构

```markdown
# <技能标题>

## Overview
一到两段：做什么，为什么需要。

## When to Use
- 触发条件（bullet 列表）
- "Don't use for:" 反触发条件

## <技能特定章节>
- 快速参考表
- 精确命令的代码块
- Hermes 特有的 recipes

## Common Pitfalls
编号列表：常见错误和修复方法。

## Verification Checklist
- [ ] 操作后验证的 checkbox 列表

## One-Shot Recipes（可选）
命名场景 → 具体命令序列。
```

### 5. 添加辅助文件

- `references/` — 按需加载的参考文档
- `templates/` — 模板文件
- `scripts/` — 辅助脚本
- `assets/` — 静态资源

### 6. 本地验证

```python
import yaml, re, pathlib
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'\n---\s*\n', content[3:])
fm = yaml.safe_load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 1024
assert len(content) <= 100_000
```

### 7. 提交

```bash
git add skills/<category>/<name>/
git commit -m "Add skill: <name>"
```

> 注意：当前会话的技能加载器在会话开始时缓存，新技能需要在新会话中才能被 `skill_view` / `skills_list` 看到。

## 关键规范

### Description 编写规范

- ≤ 1024 字符
- 以 "Use when ..." 开头，描述**触发类别**而非单一任务
- 示例：
  - ✅ "Use when debugging test failures. Enforce RED-GREEN-REFACTOR cycle."
  - ❌ "Debug tests"
  - ❌ "Be thorough when testing"

### 文件大小限制

| 限制项 | 值 | 说明 |
|--------|---|------|
| Description | ≤ 1024 字符 | 验证器强制 |
| 完整 SKILL.md | ≤ 100,000 字符 | 约 36k tokens |
| 推荐范围 | 8-14k 字符 | 官方技能平均水平 |
| 超过 20k | 拆分到 `references/*.md` | 渐进式披露 |

### 渐进式披露（三层加载）

| 层级 | 调用方式 | 内容 |
|------|---------|------|
| L0 | `skills_list()` | 仅加载基础元数据 |
| L1 | `skill_view(name)` | 加载完整 SKILL.md |
| L2 | `skill_view(name, path)` | 加载特定参考文件 |

### 触发机制

- 斜杠命令：`/<skill-name>`
- 自然语言对话
- `fallback_for_toolsets`：仅在特定高级工具缺失时显示
- `platforms`：自动隐藏不兼容操作系统的技能

### 写作质量原则

1. **优化过程可预测性** — 每一行都应改变代理行为，否则删除
2. **正确的上下文负载** — description 每次都会被加载，保持精炼
3. **信息层级** — 常用步骤放 SKILL.md，详细内容放 references/
4. **完成标准** — 每个步骤都要有可检查的完成条件
5. **规则与概念共存** — 定义、警告、示例、验证放在一起
6. **使用强引导词** — "tight loop"、"root cause"、"regression test" 比长解释更省 token
7. **消除重复和无效内容** — "Be careful"、"use best practices" 不改变行为，删除
8. **防止过早完成** — 如果代理倾向于跳过某步骤，先锐化该步骤的完成标准

## 官方参考技能

| 技能 | 路径 | 说明 |
|------|------|------|
| [Skill Authoring](https://github.com/nousresearch/hermes-agent/blob/main/skills/software-development/hermes-agent-skill-authoring/SKILL.md) | `skills/software-development/hermes-agent-skill-authoring/` | 官方技能编写指南 |
| [Test-Driven Development](https://github.com/nousresearch/hermes-agent/blob/main/skills/software-development/test-driven-development/SKILL.md) | `skills/software-development/test-driven-development/` | TDD 工作流 |
| [Systematic Debugging](https://github.com/nousresearch/hermes-agent/blob/main/skills/software-development/systematic-debugging/SKILL.md) | `skills/software-development/systematic-debugging/` | 系统化调试 |
| [Plan](https://github.com/nousresearch/hermes-agent/blob/main/skills/software-development/plan/SKILL.md) | `skills/software-development/plan/` | 任务规划 |

## 工具链

| 工具 | 用途 |
|------|------|
| `skill_manage(action='create')` | 创建用户本地技能（`~/.hermes/skills/`） |
| `skill_manage(action='patch')` | 补丁更新（支持 in-repo 和本地） |
| `skill_manage(action='write_file')` | 写入辅助文件（references/templates/scripts/assets） |
| `/learn` 命令 | 从 URL 或本地上下文自动生成技能 |
| `skill_view(name)` | 查看技能完整内容 |
| `skills_list()` | 列出所有可用技能 |

## 常见陷阱

| 陷阱 | 说明 |
|------|------|
| 用 `skill_manage(create)` 创建 in-repo 技能 | 会写到 `~/.hermes/skills/`，应用 `write_file` |
| `---` 前有空行 | 验证器检查 `startswith("---")`，会失败 |
| Description 太通用 | 应以 "Use when ..." 开头描述触发类别 |
| 缺少 author/license/metadata | 验证器不强制，但所有官方技能都有 |
| 创建重复技能 | 先 `ls skills/<category>/` 检查 |
| 期望当前会话看到新技能 | 技能加载器在会话开始时缓存 |
| 积累沉淀内容 | 技能应越来越精炼，添加新规则时删除旧措辞 |
| 无效内容 | "Be careful" 不改变行为，用可检查的完成标准替代 |