Перейти к содержанию

На этой странице Создание SKILL.md в репозитории: frontmatter, валидатор, структура.

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

|---|--- |Источник| Встроенный (установлен по умолчанию) |Путь| skills/software-development/hermes-agent-skill-authoring |Версия| 1.0.0 |Автор| Hermes Agent |Лицензия| MIT |Теги| skills, authoring, hermes-agent, conventions, skill-md |Связанные навыки| writing-plans, requesting-code-review

Справочник: полный SKILL.md​

info Ниже представлено полное определение навыка, которое Hermes загружает при активации этого навыка. Это те инструкции, которые видит агент, когда навык активен.

Создание навыков Hermes-Agent (в репозитории)

Обзор​

SKILL.md может находиться в двух местах: 1. Локально у пользователя: ~/.hermes/skills/<категория>/<имя>/SKILL.md — личное, не публикуется. Создаётся через skill_manage(action='create'). 2. В репозитории (этот навык описывает этот случай): /home/bb/hermes-agent/skills/<категория>/<имя>/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/: [code] ---
name: my-skill-name # нижний регистр, дефисы, ≤64 символа (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]
---

[/code] version / author / license / metadata НЕ проверяются валидатором, но присутствуют у всех навыков — если их опустить, ваш навык будет выглядеть чужеродно.

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

  • Описание: ≤ 1024 символов (проверяется).
  • Полный SKILL.md: ≤ 100 000 символов (проверяется как MAX_SKILL_CONTENT_CHARS, ~36k токенов).
  • Остальные навыки в software-development/ занимают 8–14 тыс. символов. Старайтесь укладываться в этот диапазон. Если переваливает за 20 тыс., разбейте на references/*.md и ссылайтесь на них из SKILL.md.

Общая структура​

Каждый навык в репозитории в целом следует такой схеме: [code] # <Заголовок> 

## Обзор  
Один-два абзаца: что и зачем.

## Когда использовать  
- Триггеры в виде маркированного списка  
- Контр-триггеры: «Не использовать для:»

## <Тематические разделы, специфичные для навыка>  
- Часто используются справочные таблицы  
- Блоки кода с точными командами  
- Рецепты для Hermes (тесты через scripts/run_tests.sh, пути ui-tui и т.д.)

## Частые ошибки  
Нумерованный список ошибок и их исправлений.

## Чек-лист проверки  
- [ ] Чекбоксы с действиями для проверки после выполнения

## Готовые сценарии (опционально)  
Именованные сценарии → конкретные последовательности команд.

[/code] Не все разделы обязательны, но Обзор + Когда использовать + содержательное тело + частые ошибки — это минимум, чтобы навык ощущался «своим».

Размещение в директориях​

[code] skills/<категория>/<имя-навыка>/SKILL.md

[/code] Категории, существующие в репозитории (уточните через 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. Выберите наиболее подходящую существующую категорию. Не создавайте новые категории верхнего уровня без необходимости.

Процесс работы​

  1. Изучите аналоги в целевой категории: [code] ls skills/<категория>/

[/code] Прочитайте 2–3 файла SKILL.md аналогов, чтобы соответствовать стилю и структуре. 2. Проверьте ограничения валидатора в tools/skill_manager_tool.py, если не уверены. 3. Напишите черновик с помощью write_file в skills/<категория>/<имя>/SKILL.md. 4. Проверьте локально: [code] 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

[/code] 5. Сделайте git add + commit в активной ветке. 6. Важно: загрузчик навыков в ТЕКУЩЕЙ сессии кэшируется — skill_view / skills_list не увидят новый навык до новой сессии. Это ожидаемое поведение, не ошибка.

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

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).
  • Всегда делайте commit после правки — навыки в репозитории являются исходным кодом, а не состоянием среды выполнения.

Частые ошибки​

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

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