authoring-hermes-skills
Author Hermes skills: user-local or in-repo SKILL.md.
- License 许可
- MIT
- 最近更新
- 2026-10-20
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- authoring-hermes-skills
- author
- Hermes Agent
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "hermes", "skills", "skill-manage", "authoring", "memory" ], "related_skills": [ "hermes-profile-management", "hermes-runtime-diagnostics" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Author Hermes skills: user-local or in-repo SKILL.md.
02 资源文件 3
- 参考文档references/background-curator-constraints.md3.1 KB
- 参考文档references/in-repo-skill-authoring.md7.9 KB
- 参考文档references/skill-validator-rules.md2.5 KB
03 SKILL.md 正文
Authoring Hermes Skills
Two trees, one discipline. Decide which tree first — the tooling, validator, and review bar differ.
| Tree | Path | How to write |
|---|---|---|
| User-local | $HERMES_HOME/skills/<category>/<name>/SKILL.md |
skill_manage(action='create' | 'patch' | 'write_file') |
| In-repo | skills/<category>/ or optional-skills/<category>/ inside the hermes-agent repo |
write_file + git add; skill_manage create does not target this tree |
For in-repo skills (tier choice, frontmatter bar, platform gating, tests, docs regeneration, PR workflow) read references/in-repo-skill-authoring.md before writing.
Shared rules
- Description is the trigger. One sentence, ≤60 chars, trigger first, ends with a period.
skill_manage(action='create')rejects longer ones and the system-prompt index truncates at 57 chars + "…" — everything needed to match the skill must fit in that window. All other detail belongs in the body. Quote the value if it contains:or YAML parses it as a mapping. Directwrite_fileedits bypass that validation, so re-check the 57-char trigger window by hand after writing a SKILL.md outsideskill_manage. - Optimize for process predictability. If a line does not change model behavior, cut it. "Be careful" and "use best practices" are no-ops; replace with a checkable criterion.
- Each step ends with a completion criterion, checkable and exhaustive when it matters ("every modified file accounted for" beats "summarize changes").
- Co-locate a rule with the concept it governs, and when adding a rule remove the wording it replaces — skills accumulate sediment otherwise.
- Support files carry depth:
references/<topic>.md(topical depth, named by topic — never by date or incident),templates/(starter files to copy),scripts/(re-runnable actions). Add withwrite_fileand one pointer line in SKILL.md. Extend an existing reference instead of adding a sibling. - Don't restate environment or tool-schema basics. A skill carries the workflow, order of operations, and pitfalls.
Procedure — user-local
- Decide NEW vs extend:
skill_viewthe candidates first. That read also satisfies the read-before-write guard for a later patch. - Draft the SKILL.md: YAML frontmatter (
name,description,version,author,license,platforms,metadata.hermes.tags/related_skills) plus a procedural body with concrete commands and pitfalls. - Apply with a single
skill_managecall; batch related edits (new skills plus therelated_skillscross-links they need on existing skills) together. - Verify:
skill_view(name)for every new/edited skill and spot-read the on-disk frontmatter. New user-local skills load immediately; no restart. (An in-repo skill is invisible to the current session — the loader initializes at session start.) - Distribution: default-profile skills mirror to named profiles via
$HERMES_HOME/scripts/sync_default_profile_extensions.py(dry-run → apply → dry-run). Never hand-copy into profile trees — the sync also deletes target-only skills there.
Pitfalls
- Atomic batches: all operations in one
skill_managecall apply together; one failure (e.g. an over-long description on acreate) rolls back every earlier op. After a rollback, re-issue the complete corrected batch — re-running only the failed op leaves the rest unapplied. - Read-before-write guard: patching an existing skill, or overwriting an existing support file, requires a fresh
skill_viewof that exact target in the current session; content quoted earlier in the conversation does not count. - Unique
old_string: a patch whose snippet matches several places fails and takes the whole batch down — include enough skill-specific context. - Protected skills: bundled and hub-installed skills refuse edits ("Refusing … for bundled skill"). Note the gap and recommend
hermes curator adopt <name>— do not retry. - Router skills: a skill whose core is a routing table pointing at siblings adds an indirection hop and duplicates their triggers. If it would be empty without "load skill X instead", don't write it.
- Dangling
related_skills: every entry must resolve in the same tree state; archived or user-only names break resolution. - Machine-local paths baked into a skill break for everyone else: write
~/.camofox/downloads,$HOME/...,%USERPROFILE%,$TEMP— neverC:\Users\<name>\...or/home/<you>/.... In shell snippets quote the expansion, not the tilde:"~/.x"passes a literal~and the command fails, so write"$HOME/.x". - Referencing raw shell instead of Hermes tools: name
terminal,read_file,write_file,patch,search_files,web_search,web_extract,browser_navigate,vision_analyze,delegate_task,cronjob— notgrep/cat/sed/find. - Wholesale rewrite of a long SKILL.md:
write_filerefuses to overwrite a file it did not read in one unpaginated pass, and reading page-by-page does not clear that guard. For a true rewrite, move the old file aside with a git/tree rollback point and write the new one; for everything smaller,patchthe offending sentences. Append no "UPDATE:" block — a stale rule left standing still gets followed. - Migrating a skill to a new tool surface: transplant the domain knowledge, but exercise each ported procedure against the live target before it lands in the doc, and label what was not exercised as unverified. Delete the superseded implementation and put a one-line deprecation header on every reference file that still prescribes it — two contradictory procedures in one skill are worse than either alone, because the next session follows the stale one.
Verification Checklist
- [ ] Tree chosen deliberately (user-local vs in-repo), and in-repo work follows
references/in-repo-skill-authoring.md. - [ ] Frontmatter starts at byte 0,
name+descriptionpresent, body non-empty. - [ ] Description ≤60 chars, trigger self-contained in the first 57, ends with a period, no marketing words.
- [ ] Every
related_skillsentry resolves. - [ ] Each ordered step has a checkable completion criterion;
## Pitfallsand verification are present. - [ ]
skill_viewloads every touched skill; on-disk frontmatter spot-read. - [ ] No manual copies into profile trees (the sync script owns distribution).
04 同仓库更多 Skills
web-retrieval-resilience
Web tools fail or search rules break: repair or fall back.
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
verification-loop
Run a six-phase verification of a Claude Code session's work — build, type check, lint, tests with coverage, security grep, and diff review — then produce a PASS/FAIL verification report. Use when verifying work after completing a feature or refactor, before creating a PR, or when quality gates must pass.
unreal-world-builder
开放世界与环境专家——精通 UE5 World Partition、Landscape、程序化植被、HLOD 和大规模关卡流式加载,打造无缝开放世界体验
unreal-technical-artist
Unreal Engine 视觉管线专家——精通材质编辑器、Niagara 特效、程序化内容生成和 UE5 项目的美术到引擎管线
unreal-systems-engineer
性能与混合架构专家——精通 C++/Blueprint 边界、Nanite 几何体、Lumen GI 和 Gameplay Ability System,面向 AAA 级 Unreal Engine 项目