Hermes 技能开发

编写仓库内 SKILL.md：frontmatter、验证器、结构规范

概述

SKILL.md 可以放在两个位置：

• 用户本地：~/.hermes/skills///SKILL.md — 个人、不共享。通过 skill_manage(action='create') 创建。
• 仓库内（本技能关注此情况）：/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 的 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  # 小写、连字符、≤64 字符 (MAX_NAME_LENGTH)
description: Use when . .
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 不被验证器强制，但每个同伴都有——省略会让你的技能显得突兀。

大小限制

• Description：≤ 1024 字符（强制）
• 完整 SKILL.md：≤ 100,000 字符（强制为 MAX_SKILL_CONTENT_CHARS，约 36k tokens）

同伴技能在 software-development/ 下约 8-14k 字符。以此为目标。如果超过 20k，拆分到 references/*.md 并从 SKILL.md 引用。

同伴匹配结构

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

# 

并非每个章节都必需，但 Overview + When to Use + 可执行正文 + pitfalls 是技能感觉像同伴的最低要求。

目录放置

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. 阅读 2-3 个同伴 SKILL.md 文件以匹配语气和结构 3. 如不确定，检查 tools/skill_manager_tool.py 中的验证器约束 4. 用 write_file 起草 skills///SKILL.md 5. 本地验证：

   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
   

6. 在活动分支上 git add + git commit 注意：当前会话的技能加载器已缓存——skill_view / skills_list 在新会话前看不到新技能。这是预期行为，不是 bug。

交叉引用其他技能

metadata.hermes.related_skills 在加载时合并两棵树（skills/ 仓库内和 ~/.hermes/skills/）。 你可以从仓库内技能引用用户本地技能，但其他用户全新克隆仓库时无法解析。 仓库内技能优先只引用仓库内技能。如果频繁引用的技能只存在于 ~/.hermes/skills/，考虑提升到仓库。

编辑现有仓库内技能

• 小修复（错字、添加 pitfall、收紧触发条件）：skill_manage(action='patch', name=..., old_string=..., new_string=...) 对仓库内技能有效
• 重大重写：write_file 整个 SKILL.md。skill_manage(action='edit') 也有效但需要提供完整新内容
• 添加支持文件：write_file 到 skills///references/*.md、templates/ 或 scripts/。skill_manage(action='write_file') 也有效并强制 references/templates/scripts/assets 子目录白名单

始终提交编辑——仓库内技能是源码，不是运行时状态。

常见陷阱

• 用 skill_manage(action='create') 创建仓库内技能。它写入 ~/.hermes/skills/，不是仓库树。仓库内创建用 write_file。
• --- 前有前导空白。验证器检查 content.startswith("---")；任何前导空行或 BOM 会导致验证失败。
• Description 太泛。同伴描述以 "Use when ..." 开头并描述触发类，不是一个任务。"Use when debugging X" > "Debug X"。
• 忘记 author/license/metadata 块。不被验证器强制，但每个同伴都有；省略让技能看起来半成品。
• 写一个重复同伴的技能。创建前，ls skills// 并打开 2-3 个同伴。优先扩展现有技能而非创建狭窄的兄弟。
• 期望当前会话看到新技能。不会。技能加载器在会话开始时初始化。在新会话中验证或通过确切路径用 skill_view。
• 链接仓库内不存在的技能。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} 都存在
• [ ] Name ≤ 64 字符，小写 + 连字符
• [ ] Description ≤ 1024 字符且以 "Use when ..." 开头
• [ ] 总文件 ≤ 100,000 字符（目标 8-15k）
• [ ] 结构：# Title → ## Overview → ## When to Use → 正文 → ## Common Pitfalls → ## Verification Checklist
• [ ] related_skills 引用在仓库内解析（或明确允许用户本地）
• [ ] git add skills/// && git commit 在预期分支上完成