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') 不会写入该目录树。/home/bb/hermes-agent/skills/ 下的现有技能(小改动用 patch,重写用 write_file;skill_manage 对仓库内技能仍可执行 patch,但不支持 create)权威来源:tools/skill_manager_tool.py::_validate_frontmatter。硬性要求:
--- 作为文件开头(前面不能有空白行)。--- 结束。name 字段。description 字段,且 ≤ 1024 字符(MAX_DESCRIPTION_LENGTH)。--- 之后正文不能为空。skills/software-development/ 下所有技能共用的结构范式:
---
name: my-skill-name # lowercase, hyphens, ≤64 chars (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 不由验证器强制,但每个同类技能都有——省略会让你的技能显得突兀。
MAX_SKILL_CONTENT_CHARS 强制,约 3.6 万 tokens)。software-development/ 中的同类技能为 8-14k 字符。以这个范围为目标。如果超过 20k,拆分为 references/*.md 并从 SKILL.md 引用。每个仓库内技能大致遵循:
#
## Overview
One or two paragraphs: what and why.
## When to Use
- Bulleted triggers
- "Don't use for:" counter-triggers
##
- 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 + 可执行的正文 + 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。
选择最接近的现有分类。不要随意发明新的顶级分类。
ls skills//
阅读 2-3 个同类 SKILL.md,以对齐语气和结构。
tools/skill_manager_tool.py。write_file 写入 skills///SKILL.md。
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
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/.md、templates/ 或 scripts/。skill_manage(action='write_file') 也可以,并且会强制 references/templates/scripts/assets 子目录白名单。skill_manage(action='create') 创建仓库内技能。它会写入 ~/.hermes/skills/,而不是仓库目录树。仓库内创建请使用 write_file。--- 前面有前导空白。验证器检查 content.startswith("---");任何前导空行或 BOM 都会导致验证失败。ls skills// 并打开 2-3 个同类。优先扩展现有技能,而不是创建一个狭窄的兄弟技能。skill_view 验证。related_skills: [some-user-local-skill] 对你有用,但对其他克隆者会失效。优先只引用仓库内技能。skills///SKILL.md(而不是 ~/.hermes/skills/)---,并以 --- 结束name、description、version、author、license、metadata.hermes.{tags, related_skills} 全部存在# Title → ## Overview → ## When to Use → 正文 → ## Common Pitfalls → ## Verification Checklistrelated_skills 引用的技能在仓库内可解析(或明确允许用户本地)git add skills/// && git commit
评论区