--- date: 2026-05-06 topic: hermes-skills-rollout status: in-progress type: domain target_promote: claude-skills sources: - .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/// ├── 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.` (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///`. **Архитектура:** ``` 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///` с вызовом `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//SKILL.hermes.md`, конвертер копирует as-is, без преобразований). ## Open questions (live) - [x] **Q1.** Maintenance model → **ongoing dual-target** (конвертер + маппинг, регенерим при каждом релизе claude-skills). Anti-drift, видимость Claude-измов, reuse под другие агенты. - [x] **Q2.** ~~Hermes-tap репо / install-script~~ → **`dist-hermes/` (pre-converted, committed) + Hermes-side installer**. Конвертация у нас в claude-skills, установка через `skill_manage(action='create')` на стороне Hermes. - [x] **Q3.** ~~Hub-публикация~~ → **out of scope** (частные скилы). - [x] **Q4.** Форма Hermes-installer'а → **installer-как-Hermes-скил** (`dist-hermes/meta/claude-skills-installer/SKILL.md`). Bootstrap: одна ручная `skill_manage` вызов для самого installer'а, дальше триггер «обнови claude-skills» — он сам итерирует по `dist-hermes///` и вызывает `skill_manage(action='create', ...)` per скил. Recursive: installer обновляется вместе со всем остальным через `git pull && trigger update`. - [x] **Q5a.** caveman family → **skip** (Hermes на дешёвой модели, мотив пропадает). - [x] **Q5b.** wiki-fork → **порти́руем наши** (independence tenet — наша schema, не зависим от Hermes built-in). - [x] **Q5c.** context7 → **mandatory adapt** (yaml-edit паттерн). - [x] **Q5d.** projects-meta → **mandatory adapt thin** (бинарь + auth уже общие из `.common`, только yaml-edit). - [x] **Q6.** `🔴 не портируется` → **`mode: skip` в `mapping.yaml` + коммитимый `dist-hermes/SKIPPED.md`** с причиной per skill. Stub-скилы НЕ пишем. Silent отвергнут. - [x] **Q7.** Версионирование → **per-skill semver mirror из claude-skills фронтматтера** (`1.0.0` default если нет). Lock-step с upstream. Bump по `project-discipline` Rule 3. - [x] **Q8.** Layout → **внутри `claude-skills/hermes/`**: - `hermes/mapping.yaml` (skill→category, replace-rules, skip-list, mode) - `hermes/skills//SKILL.md` (`mode: manual` overrides) - `scripts/build-hermes.{sh,py}` (генератор) - `dist-hermes///` (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//SKILL.md` или `hermes/skills//` для manual, применяет mapping, пишет `dist-hermes///`, генерит `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///`, вызывает `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:** `). Должен 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 должен подсказывать «эта работа закрывает таску ``?» — закрыть `extend-project-discipline-brainstorm-workspaces` и `project-creation-lifecycle-skill` тогда не пропустят (они сейчас оба ⚪ ready несмотря на `215afdd` и `23431c5` shipped).