Hermes Agent 技能编写 — 在仓库中编写 SKILL.md

{/* 此页面由 website/scripts/generate-skill-docs.py 从技能的 SKILL.md 自动生成。请编辑源文件 SKILL.md，而非此页面。 */}

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
相关技能	writing-plans、requesting-code-review

参考：完整 SKILL.md

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

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

概述

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

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

何时使用

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

必需的 Frontmatter

权威来源：tools/skill_manager_tool.py::_validate_frontmatter。硬性要求：

• 以 --- 作为第一个字节开始（无前导空行）。
• 以 \n---\n 结束，之后进入正文。
• 解析为 YAML 映射。
• 包含 name 字段。
• 包含 description 字段，长度 ≤ 1024 字符（MAX_DESCRIPTION_LENGTH）。
• 结束 --- 后有非空正文。

所有 skills/software-development/ 下技能使用的一致格式：

---
name: my-skill-name               # 小写，连字符，≤64 字符（MAX_NAME_LENGTH）
description: Use when <触发条件>. <一行行为描述>.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    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 中引用。

同级匹配的结构

每个仓库内技能大致遵循：

# <标题>

## 概述
一至两段：是什么和为什么。

## 何时使用
- 项目符号触发条件
- 反例：何时"不"使用

## <技能特定主题章节>
- 常用快速参考表
- 含精确命令的代码块
- Hermes 特定配方（通过 scripts/run_tests.sh 的测试、ui-tui 路径等）

## 常见陷阱
带修复方法的编号列表。

## 验证清单
- [ ] 操作后验证的复选框列表

## 一次性配方（可选）
命名场景 → 具体命令序列。

并非每个章节都是必需的，但 概述 + 何时使用 + 可操作正文 + 陷阱是使其达到同级水平的最低要求。

目录放置

skills/<分类>/<技能名称>/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。

选择最近似的现有分类。不要随意创建新的顶级分类。

工作流程

1. 调查目标分类中的同级技能：

   ls skills/<分类>/
   

   阅读 2-3 个同级 SKILL.md 文件以匹配语气和结构。
2. 如有疑问，检查验证器约束，在 tools/skill_manager_tool.py 中。
3. 起草：使用 write_file 写入 skills/<分类>/<名称>/SKILL.md。
4. 本地验证：

   import yaml, re, pathlib
   content = pathlib.Path("skills/<分类>/<名称>/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

5. Git add + commit 到当前活跃分支。
6. 注意： 当前会话的技能加载器已缓存——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/<分类>/<名称>/references/<file>.md、templates/<file> 或 scripts/<file>。skill_manage(action='write_file') 同样有效，并强制限定在 references/templates/scripts/assets 子目录白名单内。
• 始终提交编辑——仓库内技能是源代码，而非运行时状态。

常见陷阱

1. 对仓库内技能使用 skill_manage(action='create')。 它会写入 ~/.hermes/skills/，而非仓库树。创建仓库内技能应使用 write_file。

2. --- 前有前导空白。 验证器检查 content.startswith("---")；任何前导空行或 BOM 都会导致验证失败。

3. 描述过于泛化。 同级技能的描述以 “Use when …” 开头，描述的是触发类而非单个任务。“Use when debugging X” > “Debug X”。

4. 忘记作者/许可证/元数据块。 虽非验证器强制，但所有同级技能都包含；省略会使技能显得半成品。

5. 编写与同级技能重复的技能。 创建前先 ls skills/<分类>/ 并打开 2-3 个同级技能。优先扩展现有技能，而非创建狭窄的兄弟技能。

6. 期望当前会话能立即看到新技能。 不会。技能加载器在会话启动时初始化。在新会话中验证，或通过 skill_view 使用精确路径验证。

7. 链接到仓库中不存在的技能。 related_skills: [some-user-local-skill] 对你有效，但会破坏其他克隆。优先仅链接仓库内技能。

验证清单

• 文件位于 skills/<分类>/<名称>/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/<分类>/<名称>/ && git commit 在目标分支上完成