Hermes Agent Skill Authoring

Создание SKILL.md в репозитории: фронтматтер, валидатор, структура.

Метаданные навыка


Источник	Встроенный (установлен по умолчанию)
Путь	`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 загружает при его активации. Именно это агент видит как инструкции во время работы навыка.

Authoring Hermes-Agent Skills (in-repo)

Обзор

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 — нет)

Обязательный фронтматтер

Источник истины: 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 <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 валидатором не проверяются, но они есть у каждого соседа — без них навык будет выбиваться из общего стиля.

Ограничения по размеру

Description: ≤ 1024 символов (проверяется).
Весь SKILL.md: ≤ 100 000 символов (ограничение MAX_SKILL_CONTENT_CHARS, ~36k токенов).
Соседние навыки в 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 не увидят новый навык до начала новой сессии. Это ожидаемое поведение, не баг.

Перекрёстные ссылки на другие навыки

metadata.hermes.related_skills при загрузке объединяет оба дерева (skills/ из репозитория и ~/.hermes/skills/). Ссылаться на пользовательский навык из репозиторного технически можно, но у тех, кто клонирует репозиторий с нуля, такая ссылка не разрешится. Из репозиторных навыков ссылайся только на другие репозиторные. Если часто используемый навык живёт только в ~/.hermes/skills/, рассмотри его перенос в репозиторий.

Редактирование существующих навыков в репозитории

Мелкая правка (опечатка, новый пункт в pitfalls, уточнение триггера): skill_manage(action='patch', name=..., old_string=..., new_string=...) отлично работает с репозиторными навыками.
Масштабная переработка: пиши весь SKILL.md заново через write_file. skill_manage(action='edit') тоже подойдёт, но потребует полного нового содержимого.
Добавление вспомогательных файлов: используй write_file в skills/<category>/<name>/references/<file>.md, templates/<file> или scripts/<file>. skill_manage(action='write_file') также работает и проверяет, что путь входит в allowlist подпапок (references/templates/scripts/assets).
Всегда коммить изменения — репозиторные навыки являются исходниками, а не рантаймовым состоянием.

Типичные ошибки

Использование skill_manage(action='create') для репозиторного навыка. Этот вызов пишет в ~/.hermes/skills/, а не в дерево репозитория. Для создания навыка в репозитории используй write_file.
Пробел или пустая строка перед ---. Валидатор проверяет content.startswith("---"); любой лидирующий пробел, пустая строка или BOM провалит проверку.
Слишком общее описание. Описания у соседей начинаются с «Use when …» и описывают класс триггеров, а не одну конкретную задачу. «Use when debugging X» лучше, чем «Debug X».
Отсутствие блока author/license/metadata. Валидатор это не проверяет, но он есть у каждого соседа; без него навык выглядит незаконченным.
Дублирование существующего навыка. Перед созданием выполни ls skills/<category>/ и открой 2–3 соседних файла. Лучше расширить существующий навык, чем создавать узкий дубль рядом.
Ожидание, что текущая сессия увидит новый навык. Не увидит. Загрузчик инициализируется при старте сессии. Проверяй в новой сессии или через skill_view с точным путём.
Ссылки на навыки, которых нет в репозитории. related_skills: [some-user-local-skill] работает у тебя, но ломается при свежем клоне. Ссылайся только на репозиторные навыки.

Чеклист проверки

Файл находится в skills/<category>/<name>/SKILL.md (не в ~/.hermes/skills/)
Фронтматтер начинается с байта 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/<category>/<name>/ && git commit выполнен в нужной ветке