Promote hermes-skills-rollout → claude-skills wiki + 7 tasks; archive

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>
This commit is contained in:
2026-05-07 00:03:43 +03:00
parent f3cad514db
commit e749570e6c
3 changed files with 258 additions and 0 deletions

View File

@@ -0,0 +1,210 @@
---
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).

View File

@@ -25,3 +25,6 @@ Events: `started`, `promoted`, `registered`, `archived`.
2026-05-06 bootstrapped factory project (.tasks/STATUS.md + .wiki/ canonical layout, commit ecddcdf — fixed projects-meta sync indexing prerequisite)
2026-05-06 promoted factory-bootstrap → factory/.wiki/concepts/factory-bootstrap.md (commits 549fe2ea+d26da137+b79be591); tasks created: factory#factory-bootstrap-script (ready), factory#factory-l1-design (blocked-by factory-bootstrap-script); also claude-skills#project-creation-lifecycle-skill (ready, gap surfaced during this promote)
2026-05-06 archived factory-bootstrap → .archive/2026-05-06-factory-bootstrap.md
2026-05-06 designed hermes-skills-rollout (.brainstorm/hermes-skills-rollout.md — domain spec, target promote: claude-skills)
2026-05-06 promoted hermes-skills-rollout → 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), claude-skills#hermes-installer-skill (blocked), claude-skills#hermes-mvp-coverage (blocked), claude-skills#hermes-converter-ci (blocked, deferred), common#tasks-close-normalize-body (ready, discipline pre-req), claude-skills#using-tasks-close-coverage-gate (ready, discipline pre-req)
2026-05-06 archived hermes-skills-rollout → .archive/2026-05-06-hermes-skills-rollout.md

View File

@@ -0,0 +1,45 @@
А как тебе новые скилы добавить?
────────────────────────────────────────
┊ 📚 skill hermes-agent-skill-authoring 0.0s
─ ⚕ Hermes ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Есть два способа добавить скиллы в Hermes:
1. Локальные (только для тебя) — через skill_manage(action='create'):
Пишутся в ~/.hermes/skills/<категория>/<имя>/SKILL.md. Работают только на твоей машине, не переносятся на другие.
2. В репозитории (как раз то, что ты склонировал) — через write_file:
Пишутся в дерево репозитория skills/<категория>/<имя>/SKILL.md, коммитятся, пушатся — и становятся доступны всем, кто клонирует репу.
Структура SKILL.md:
yaml
name: my-cool-skill
description: Use когда <триггер>. <что делает>.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
hermes:
tags: [tag1, tag2]
related_skills: [other-skill]
My Cool Skill
Overview
Краткое описание: что и зачем.
When to Use
- Когда триггер X
- Не использовать для: Y
<Разделы с инструкциями>
...
Common Pitfalls
1. Типичная ошибка → как исправить
Verification Checklist
- [ ] Проверка 1
Категории уже есть в репе: 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 и др.
Хочешь создать новый скилл? Скажи какой — я подготовлю SKILL.md, запишу в репозиторий и закоммичу.