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)​

大小限制​

對等匹配結構​

目錄放置​

工作流​

交叉引用其他技能​

編輯現有的倉庫內技能​

常見陷阱​

驗證清單​