discussions/.archive/2026-05-06-hermes-skills-rollout.md

date, topic, status, type, target_promote, sources

date	topic	status	type	target_promote	sources
2026-05-06	hermes-skills-rollout	in-progress	domain	claude-skills	.wiki/raw/research/hermes-agent-skills/how-to-create.md https://hermes-agent.nousresearch.com/docs/user-guide/features/skills https://hermes-agent.nousresearch.com/docs/guides/work-with-skills https://www.glukhov.org/ai-systems/hermes/authoring-hermes-skill/ https://github.com/mudrii/hermes-agent-docs/blob/main/skills.md https://deepwiki.com/NousResearch/hermes-agent/8-skills-system

Hermes Skills Rollout — design buffer

Раскатить наш claude-skills репозиторий на Hermes Agent (Nous Research). Hermes и Claude формально совместимы по agentskills.io, но различия по фронтматтеру, раскладке (категории) и body-секциям требуют конвертации, не просто копирования.

Context

Hermes — агент от Nous Research, поддерживает SKILL-формат. Юзер уже клонировал hermes-репу (упоминается в research-файле). У нас 21 скил в ~/projects/claude-skills/skills/. Нужно понять: формат, что портируется, как поддерживать.

Hermes skill format (verified by web)

Frontmatter:

Field	Required	Notes
name	✅	lowercase-hyphen
description	✅	search-result style; считается по токенам (level-0)
version	✅	semver, должен матчить git-tag релиза
author, license	⬜	typical: MIT
platforms	⬜	[macos, linux, windows] — silently hides на не-целевой OS
metadata.hermes.tags	⬜	indexed labels (e.g. [devops, backups, shell])
metadata.hermes.category	⬜	grouping (определяет папку)
metadata.hermes.related_skills	⬜	cross-refs
metadata.hermes.requires_toolsets / requires_tools	⬜	visibility gate
metadata.hermes.fallback_for_toolsets / fallback_for_tools	⬜	"show only if premium tool absent"
metadata.hermes.config	⬜	non-secret prefs (key,description,default,prompt)
metadata.hermes.required_environment_variables	⬜	.env injection в execute_code/terminal
metadata.hermes.required_credential_files	⬜	OAuth/SA mounting

Body sections (recommended outline):

1. ## When to Use
2. ## Quick reference
3. ## Procedure
4. ## Pitfalls
5. ## Verification

Layout:

~/.hermes/skills/<category>/<skill-name>/
├── SKILL.md          (required)
├── references/       (long tables, vendor docs — pulled by skill_view(name, file))
├── templates/
├── scripts/
└── assets/

Категории — Hermes-стандартный набор: autonomous-ai-agents, creative, data-science, devops, email, gaming, github, mcp, media, mlops, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development.

Distribution: публичный git-tap. Юзер делает hermes skills tap add owner/repo. Релизы — git-теги, version фронтматтера = тег. Hub-публикация — security scan.

Design tenet: independence

Мы не зависим от Hermes built-in скилов. Где у нас и у Hermes есть аналог по функции (например llm-wiki), ставим наш. Hermes built-in тоже остаётся, но наша schema и наш темп развития — суверенны. Override через skill_manage precedence (locally modified bundled skills are preserved).

Исключение — Hermes-нативные тулы (не скилы): skills_list(), cronjob, execute_code и т.п. Это инфраструктура, не «их скил». Используем напрямую.

Hermes' inventory (key findings)

• research/llm-wiki — встроен (Karpathy). Покрывает init+operate+lint. Использует SCHEMA.md (не .wiki/CLAUDE.md). Секции entities/concepts/comparisons/queries (у нас entities/concepts/packages/sources). .tasks/ НЕ трогает. Не drop-in замена нашему — другая schema.
• mcp/native-mcp — встроен MCP-клиент. Внешние сервера через ~/.hermes/config.yaml > mcp_servers.<name> (stdio/HTTP, env-vars, auto-discovery, /reload-mcp команда).
• skills_list() — встроенный progressive disclosure (Level 0). Делает find-skills лишним.
• Hermes на Linux (/opt/data/projects в твоём скриншоте), модель glm-5.1 (Nous, дешёвая) → caveman экономия токенов не нужна.
• Cron встроен tool-сом → using-projects-meta + cron = автосинк фабричных проектов.

Audit (post-discoveries, factory-relevance × Hermes-side fit)

Skill	Решение	Reasoning
pulling-before-work	✅ MVP	универсально, нет аналога
using-markitdown	✅ MVP	через execute_code
active-platform	✅ MVP	shell-идиома (Hermes на Linux)
project-discipline	✅ MVP	workflow-правила
setup-tasks / using-tasks	✅ adapt	Hermes' llm-wiki .tasks/ не покрывает
setup-wiki / using-wiki	✅ adapt	наша schema, наш контроль (override Hermes built-in llm-wiki через skill_manage precedence)
setup-projects-meta (Hermes-flavour)	✅ adapt-mandatory	thin wrapper: бинарь уже в ~/projects/.common/lib/projects-meta-mcp/ (общефабричная инфра), auth.toml тоже общий → только yaml-edit ~/.hermes/config.yaml + /reload-mcp. Никаких клонов/билдов на Hermes-стороне
using-projects-meta	✅ adapt-mandatory	тулы auto-injected; политика та же
project-bootstrap	⚠️ adapt	зависит от wiki-fork
setup-context7 (Hermes-flavour)	✅ adapt-mandatory	yaml-edit ~/.hermes/config.yaml > mcp_servers.context7, env API-key, /reload-mcp. Тот же паттерн что projects-meta.
using-context7	✅ adapt-mandatory	политика та же, тулы auto-injected
caveman×5	❌ skip	Hermes-модель дешёвая, мотив пропадает
setup-interns / using-interns	❌ skip	Hermes сам — «cheap intern»
find-skills	❌ skip	Hermes имеет skills_list()

MVP locked (post-decisions):

• 4 универсальных: pulling-before-work, active-platform, project-discipline, using-markitdown
• 2 tasks: setup-tasks, using-tasks
• 2 projects-meta: setup-projects-meta (Hermes-flavour, thin), using-projects-meta
• 2 wiki: setup-wiki, using-wiki (наша schema, override Hermes built-in)
• 2 context7: setup-context7 (Hermes-flavour, thin), using-context7
• 1 bootstrap: project-bootstrap (orchestrator над всем выше; адаптируется последним)

= 13 скилов. (Skip: caveman×5, interns×2, find-skills.)

In-flight в claude-skills (учитываем)

• [setup-projects-meta-token-leak] ready (security fix — extraheader вместо URL-creds). Hermes-версия пишется сразу с правильным паттерном.
• [install-ps1] ready (PowerShell parity). Для Hermes-installer'а понадобится cross-platform логика.
• [skills-grouping-revisit] triggers на >30 скилов. С Hermes-добавкой подходим к порогу.

Категория-маппинг (черновик)

• pulling-before-work, project-discipline, project-bootstrap, active-platform → software-development
• setup-tasks, using-tasks → productivity
• using-markitdown → productivity или research
• setup-projects-meta, using-projects-meta → mcp
• setup-wiki, using-wiki (если порти́руем) → research

Recommendation: pre-converted dist-hermes/ + Hermes-side installer

Это частные скилы фабрики. Отметаем tap/Hub/публикацию. Установка — через skill_manage(action='create') на стороне Hermes.

User-flow: на фабричной машине git clone claude-skills → команда Hermes «установи скилы» → он итерирует, вызывает skill_manage per файл → скилы в ~/.hermes/skills/<category>/<name>/.

Архитектура:

claude-skills/
├── skills/                     ← source-of-truth (Claude-формат)
├── dist/                       ← .skill архивы для Claude (есть)
├── dist-hermes/                ← pre-converted Hermes-tree (committed, NEW)
│   ├── productivity/caveman/SKILL.md
│   ├── productivity/caveman-commit/SKILL.md
│   ├── software-development/pulling-before-work/SKILL.md
│   └── meta/claude-skills-installer/SKILL.md  ← bootstrap
├── scripts/
│   ├── build.sh / build.ps1     (есть)
│   ├── install.sh               (есть)
│   └── build-hermes.{sh,py}     (NEW — конвертер skills/* → dist-hermes/*)
└── hermes-mapping.yaml          (NEW — skill → category, replace-rules, skip-list)

Разделение труда:

• На стороне claude-skills (у нас): build-hermes.{sh,py} читает skills/*, применяет hermes-mapping.yaml (category, фронтматтер, секции, replace-rules для тулов), пишет в dist-hermes/. Запускается локально или в CI на push to master. dist-hermes/ коммитится в репу.
• На стороне Hermes (на фабрике): простая итерация по dist-hermes/<cat>/<name>/ с вызовом skill_manage(action='create', ...) per файл. Никакой conversion-логики там нет.

Почему dist-hermes коммитится, а не генерится при install:

• Аналог уже committed dist/.skill — установившаяся практика в репе.
• Hermes не нуждается в Python-окружении / нашем hermes-mapping.yaml парсере.
• Diff в dist-hermes/ виден в PR-ах — review-able, не магия.
• Bootstrap проще: clone + один Hermes-trigger.

Почему не ручной перенос в ~/.hermes/skills/:

• Анти-дрейф: claude-skills растёт. Через месяц рассинх.
• Видимость Claude-измов: конвертер падает / помечает на каждом mcp__*/Read-рефе — авто-lint совместимости.
• Reuse: agentskills.io открытый. Тот же скрипт с другим маппингом → Codex / Gemini target позже.

Trade-off: конвертер растёт нелинейно с количеством Claude-измов. Запасной план — mode: manual пер-скил в маппинге (готовый Hermes-вариант лежит в skills/<name>/SKILL.hermes.md, конвертер копирует as-is, без преобразований).

Open questions (live)

• Q1. Maintenance model → ongoing dual-target (конвертер + маппинг, регенерим при каждом релизе claude-skills). Anti-drift, видимость Claude-измов, reuse под другие агенты.
• Q2. Hermes-tap репо / install-script → dist-hermes/ (pre-converted, committed) + Hermes-side installer. Конвертация у нас в claude-skills, установка через skill_manage(action='create') на стороне Hermes.
• Q3. Hub-публикация → out of scope (частные скилы).
• Q4. Форма Hermes-installer'а → installer-как-Hermes-скил (dist-hermes/meta/claude-skills-installer/SKILL.md). Bootstrap: одна ручная skill_manage вызов для самого installer'а, дальше триггер «обнови claude-skills» — он сам итерирует по dist-hermes/<category>/<name>/ и вызывает skill_manage(action='create', ...) per скил. Recursive: installer обновляется вместе со всем остальным через git pull && trigger update.
• Q5a. caveman family → skip (Hermes на дешёвой модели, мотив пропадает).
• Q5b. wiki-fork → порти́руем наши (independence tenet — наша schema, не зависим от Hermes built-in).
• Q5c. context7 → mandatory adapt (yaml-edit паттерн).
• Q5d. projects-meta → mandatory adapt thin (бинарь + auth уже общие из .common, только yaml-edit).
• Q6. 🔴 не портируется → mode: skip в mapping.yaml + коммитимый dist-hermes/SKIPPED.md с причиной per skill. Stub-скилы НЕ пишем. Silent отвергнут.
• Q7. Версионирование → per-skill semver mirror из claude-skills фронтматтера (1.0.0 default если нет). Lock-step с upstream. Bump по project-discipline Rule 3.
• Q8. Layout → внутри claude-skills/hermes/:
  • hermes/mapping.yaml (skill→category, replace-rules, skip-list, mode)
  • hermes/skills/<name>/SKILL.md (mode: manual overrides)
  • scripts/build-hermes.{sh,py} (генератор)
  • dist-hermes/<category>/<name>/ (autogenerated, committed)
  • dist-hermes/meta/claude-skills-installer/SKILL.md (recursive bootstrap)
  • dist-hermes/SKIPPED.md (skip-log)

Action items

Все таски в claude-skills (это его доменный roadmap).

• hermes-converter-mvp — построить infra и пропустить через неё 4 универсальных скила.

  • Создать hermes/mapping.yaml (схема: per-skill mode, category, replace-rules, skip-list + reason).
  • Написать scripts/build-hermes.{sh,py} (читает skills/<name>/SKILL.md или hermes/skills/<name>/ для manual, применяет mapping, пишет dist-hermes/<category>/<name>/, генерит dist-hermes/SKIPPED.md).
  • Прогнать через 4 universal: pulling-before-work, active-platform, project-discipline, using-markitdown.
  • Закоммитить dist-hermes/ для этих 4 в репу.
  • Pre-encode security lessons: extraheader-pattern (от [setup-projects-meta-token-leak]) и POSIX-absolute paths (от [setup-interns-fix-paths]/[using-projects-meta-fix-paths]) — учесть при адаптации.

• hermes-flavour-mcp-setups — переписать setup-projects-meta и setup-context7 в Hermes-flavour (yaml-edit ~/.hermes/config.yaml > mcp_servers, /reload-mcp). Лежат как mode: manual в hermes/skills/setup-projects-meta-hermes/ и hermes/skills/setup-context7-hermes/. Pre-check на existing бинарь в ~/projects/.common/lib/projects-meta-mcp/ и ~/.config/projects-mcp/auth.toml. Применить extraheader-pattern сразу.

• hermes-installer-skill — написать dist-hermes/meta/claude-skills-installer/SKILL.md (Hermes loops по dist-hermes/<category>/<name>/, вызывает skill_manage(action='create', ...) per файл, рекурсивно копирует references//scripts//templates//assets/). Документировать bootstrap-процедуру в claude-skills/README.md (Linux/Hermes раздел).

• hermes-mvp-coverage — расширить mapping и пропустить через converter оставшиеся 9 MVP-скилов: setup-tasks, using-tasks, setup-wiki, using-wiki, using-projects-meta, using-context7, project-bootstrap (адаптируется последним — orchestrator). Smoke-test на фабричной Linux-машине: clone → trigger installer → hermes skills list показывает все 13.

• (deferred) hermes-converter-ci — GitHub-Action / Gitea-pipeline на push to master: build-hermes.{sh,py} → diff dist-hermes/ → auto-commit (или PR). Не блокирующее MVP, делается после первой ручной валидации.

Discipline pre-requisites (не блокирующие, но желательны до старта hermes-tasks)

Из код-ревью factory-bootstrap fallout 2026-05-06 — две process-гнили, чинить чтобы новые hermes-таски попали в нормальный flow:

• tasks-close-normalize-body (target: common) — tasks_close MCP-инструмент сейчас меняет только эмодзи в H2 + врезает HTML-комент, body остаётся stale (**Status:** ready + **Where I stopped:** (not started) + **Next action:** <unfulfilled plan>). Должен normalize: **Status:** done, replace **Where I stopped:** с close-note narrative, reset **Next action:** → (none — kept until merged). Видно во всех 4 closed-tasks в common/.tasks/STATUS.md (knowledge-getfrom-meta-alias, knowledge-search-reindex, tasks-aggregate-ready-filter-ux, skip-archived-repos-in-listuserrepos). Требует фикса в src/tools/tasks.ts close-handler + tests.

• using-tasks-close-coverage-gate (target: claude-skills) — using-tasks SKILL должен требовать coverage-проверку acceptance-criteria тестами перед вызовом tasks_close. Сейчас implementer закрывает по «150/150 tests pass» (existing suite), не покрывая новую логику. Ярко видно на 3 из 4 common-фиксов — acceptance criteria требовали regression-тестов, не написаны (no test for cached = null invalidation, no test for AggregateStatusEnum validation error, partial test for archived filter). Также: после feat:/fix: коммита skill должен подсказывать «эта работа закрывает таску <slug>?» — закрыть extend-project-discipline-brainstorm-workspaces и project-creation-lifecycle-skill тогда не пропустят (они сейчас оба ⚪ ready несмотря на 215afdd и 23431c5 shipped).