Hermes Agent 技能编写

编写仓库内的 SKILL.md：frontmatter（前置元数据）、验证器、结构。

技能元数据


来源	捆绑（默认安装）
路径	`skills/software-development/hermes-agent-skill-authoring`
版本	`1.0.0`
作者	Hermes Agent
许可证	MIT
平台	linux, macos, windows
标签	`skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md`
相关技能	`plan`, `requesting-code-review`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理所看到的指令。

编写 Hermes-Agent 技能（仓库内）

概述

SKILL.md 可以存在于两个位置：

用户本地： ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — 个人使用，不共享。通过 skill_manage(action='create') 创建。
仓库内（本技能针对此情况）： /home/bb/hermes-agent/skills/<category>/<name>/SKILL.md — 已提交，随包分发。使用 write_file + git add。skill_manage(action='create') 不针对此目录树。

何时使用

用户要求你在“此分支 / 仓库 / 提交”中添加技能
你正在提交一个应与 hermes-agent 一起分发的可复用工作流
你正在编辑 /home/bb/hermes-agent/skills/ 下的现有技能（小修改使用 patch，重写使用 write_file；skill_manage 仍可用于对仓库内技能进行 patch，但不支持 create）

必需的前置元数据 (Frontmatter)

事实来源：tools/skill_manager_tool.py::_validate_frontmatter。硬性要求：

以 --- 作为起始字节（无前导空行）。
在正文之前以 \n---\n 闭合。
解析为 YAML 映射。
存在 name 字段。
存在 description 字段，长度 ≤ 1024 个字符 (MAX_DESCRIPTION_LENGTH)。
闭合的 --- 之后有非空正文。

skills/software-development/ 下每个技能使用的对等匹配形状：

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Use when <trigger>. <one-line behavior>.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [short, descriptive, tags]
    related_skills: [other-skill, another-skill]
---

验证器不强制要求 version / author / license / metadata，但每个对等技能都包含它们 — 省略会使你的技能显得格格不入。

大小限制

描述：≤ 1024 个字符（强制执行）。
完整 SKILL.md：≤ 100,000 个字符（作为 MAX_SKILL_CONTENT_CHARS 强制执行，约 36k tokens）。
software-development/ 中的对等技能位于 8-14k 个字符。目标是该范围。如果超过 20k，请拆分为 references/*.md 并从 SKILL.md 中引用它们。

对等匹配结构

每个仓库内技能大致遵循以下结构：

# <Title>

## Overview
One or two paragraphs: what and why.

## When to Use
- Bulleted triggers
- "Don't use for:" counter-triggers

## <Topic sections specific to the skill>
- Quick-reference tables are common
- Code blocks with exact commands
- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)

## Common Pitfalls
Numbered list of mistakes and their fixes.

## Verification Checklist
- [ ] Checkbox list of post-action verifications

## One-Shot Recipes (optional)
Named scenarios → concrete command sequences.

并非每个部分都是必需的，但 Overview（概述）+ When to Use（何时使用）+ 可操作的正文 + 常见陷阱是使技能感觉像对等技能的最小要求。

目录放置

skills/<category>/<skill-name>/SKILL.md

仓库中当前的类别（通过 ls skills/ 确认）：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。

选择最接近的现有类别。不要随意发明新的顶级类别。

工作流

调查目标类别中的对等技能：
```
ls skills/<category>/
```
阅读 2-3 个对等 SKILL.md 文件以匹配语气和结构。
如果不确定，检查 tools/skill_manager_tool.py 中的验证器约束。
使用 write_file 将草稿写入 skills/<category>/<name>/SKILL.md。

本地验证：

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

在当前分支上 Git add + commit。
注意： 当前会话的技能加载器是缓存的 — 直到新会话开始，skill_view / skills_list 才会看到新技能。这是预期行为，不是 bug。

交叉引用其他技能

metadata.hermes.related_skills 在加载时联合两棵树（仓库内的 skills/ 和 ~/.hermes/skills/）。你可以从仓库内技能引用用户本地技能，但对于全新克隆仓库的其他用户，它将无法解析。建议仅从仓库内技能引用其他仓库内技能。如果经常引用的技能仅存在于 ~/.hermes/skills/ 中，请考虑将其提升到仓库中。

编辑现有的仓库内技能

小修复（拼写错误、添加陷阱、收紧触发条件）： skill_manage(action='patch', name=..., old_string=..., new_string=...) 在仓库内技能上运行良好。
重大重写： 使用 write_file 写入整个 SKILL.md。skill_manage(action='edit') 也有效，但需要提供完整的新内容。
添加支持文件： 使用 write_file 写入 skills/<category>/<name>/references/<file>.md、templates/<file> 或 scripts/<file>。skill_manage(action='write_file') 也有效，并强制执行 references/templates/scripts/assets 子目录允许列表。
始终提交 编辑 — 仓库内技能是源代码，而非运行时状态。

常见陷阱

对仓库内技能使用 skill_manage(action='create')。 它会将文件写入 ~/.hermes/skills/，而非仓库目录树中。若要在仓库内创建，请使用 write_file。
--- 前存在前导空白字符。 验证器会检查 content.startswith("---")；任何前导空行或 BOM（字节顺序标记）都会导致验证失败。
描述过于泛泛。 同类技能的描述应以“Use when ...”（当...时使用）开头，并描述触发场景类别，而非单一任务。“Use when debugging X”（当调试 X 时使用）优于“Debug X”（调试 X）。
遗漏作者/许可证/元数据块。 虽然验证器不强制要求，但所有同类技能均包含此块；省略会使技能看起来未完成。
编写与现有技能重复的技能。 在创建之前，执行 ls skills/<category>/ 并打开 2-3 个同类技能查看。优先扩展现有技能，而非创建功能狭窄的兄弟技能。
期望当前会话能立即看到新技能。 事实并非如此。技能加载器在会话启动时初始化。请在全新会话中验证，或通过 skill_view 使用确切路径进行验证。
链接到仓库中不存在的技能。 related_skills: [some-user-local-skill] 在你本地有效，但会导致其他克隆版本出错。优先仅使用仓库内的链接。

验证清单

文件位于 skills/<category>/<name>/SKILL.md（不在 ~/.hermes/skills/ 中）
Frontmatter 从第 0 字节开始，以 --- 开头，以 \n---\n 结尾
name、description、version、author、license、metadata.hermes.{tags, related_skills} 均存在
名称长度 ≤ 64 个字符，仅包含小写字母和连字符
描述长度 ≤ 1024 个字符，且以“Use when ...”开头
文件总大小 ≤ 100,000 个字符（目标为 8-15k）
结构：# Title → ## Overview → ## When to Use → 正文 → ## Common Pitfalls → ## Verification Checklist
related_skills 引用在仓库内可解析（或明确允许为用户本地技能）
已在目标分支上完成 git add skills/<category>/<name>/ && git commit

技能元数据​

参考：完整 SKILL.md​

编写 Hermes-Agent 技能（仓库内）

概述​

何时使用​

必需的前置元数据 (Frontmatter)​

大小限制​

对等匹配结构​

目录放置​

工作流​

交叉引用其他技能​

编辑现有的仓库内技能​

常见陷阱​

验证清单​