vitya
e749570e6c
Design doc: claude-skills/.wiki/concepts/hermes-skills-rollout-design.md (commits b3dc1251 + 5ae14fd6 + 0f65e057). Tasks created: - claude-skills#hermes-converter-mvp (ready) - claude-skills#hermes-flavour-mcp-setups (blocked-by hermes-converter-mvp) - claude-skills#hermes-installer-skill (blocked-by hermes-converter-mvp) - claude-skills#hermes-mvp-coverage (blocked-by 3 upstream) - claude-skills#hermes-converter-ci (blocked-by hermes-mvp-coverage, deferred) - common#tasks-close-normalize-body (ready, discipline pre-req) - claude-skills#using-tasks-close-coverage-gate (ready, discipline pre-req — extended 879957d9 to also cover scope-priority at recommendation time) Buffer archived from .brainstorm/ → .archive/2026-05-06-hermes-skills-rollout.md. Research clippings captured at .wiki/raw/research/hermes-agent-skills/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
211 lines
19 KiB
Markdown
211 lines
19 KiB
Markdown
---
|
||
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/<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)
|
||
|
||
- [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/<category>/<name>/` и вызывает `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/<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).
|