There are two places a SKILL.md can live:
~/.hermes/skills///SKILL.md — personal, not shared. Created via skill_manage(action='create')./home/bb/hermes-agent/skills///SKILL.md — committed, shipped with the package. Use write_file + git add. skill_manage(action='create') does NOT target this tree./home/bb/hermes-agent/skills/ (use patch for small edits, write_file for rewrites; skill_manage still works for patch on in-repo skills, but not for create)Source of truth: tools/skill_manager_tool.py::_validate_frontmatter. Hard requirements:
--- as the first bytes (no leading blank line).n---n before the body.name field present.description field present, ≤ 1024 chars (MAX_DESCRIPTION_LENGTH).---.Peer-matched shape used by every skill under 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 are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.
MAX_SKILL_CONTENT_CHARS, ~36k tokens).software-development/ sit at 8-14k chars. Aim for that range. If you're pushing past 20k, split into references/*.md and reference them from SKILL.md.Every in-repo skill follows roughly:
#
## 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.
Not every section is mandatory, but Overview + When to Use + actionable body + pitfalls are the minimum for the skill to feel like a peer.
skills///SKILL.md
Categories currently in repo (confirm with 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.
Pick the closest existing category. Don't invent new top-level categories casually.
ls skills//
Read 2-3 peer SKILL.md files to match tone and structure.
tools/skill_manager_tool.py if unsure.write_file to 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 will not see the new skill until a new session. This is expected, not a bug.metadata.hermes.related_skills unions both trees (skills/ in-repo and ~/.hermes/skills/) at load time. You CAN reference a user-local skill from an in-repo skill, but it won't resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in ~/.hermes/skills/, consider promoting it to the repo.
skill_manage(action='patch', name=..., old_string=..., new_string=...) works fine on in-repo skills.write_file the whole SKILL.md. skill_manage(action='edit') also works but requires supplying the full new content.write_file to skills///references/.md, templates/, or scripts/. skill_manage(action='write_file') also works and enforces the references/templates/scripts/assets subdir allowlist.skill_manage(action='create') for an in-repo skill. It writes to ~/.hermes/skills/, not the repo tree. Use write_file for in-repo creation.---. The validator checks content.startswith("---"); any leading blank line or BOM fails validation.ls skills// and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling.skill_view using the exact path.related_skills: [some-user-local-skill] works for you but breaks for other clones. Prefer only in-repo links.skills///SKILL.md (not in ~/.hermes/skills/)---, closes with n---nname, description, version, author, license, metadata.hermes.{tags, related_skills} all present# Title → ## Overview → ## When to Use → body → ## Common Pitfalls → ## Verification Checklistrelated_skills references resolve in-repo (or are explicitly OK to be user-local)git add skills/// && git commit completed on the intended branch
评论区