From e749570e6c99b0410e70ca18fb101f9e7f0592e1 Mon Sep 17 00:00:00 2001 From: vitya Date: Thu, 7 May 2026 00:03:43 +0300 Subject: [PATCH] =?UTF-8?q?Promote=20hermes-skills-rollout=20=E2=86=92=20c?= =?UTF-8?q?laude-skills=20wiki=20+=207=20tasks;=20archive?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- .archive/2026-05-06-hermes-skills-rollout.md | 210 ++++++++++++++++++ .wiki/log.md | 3 + .../hermes-agent-skills/how-to-create.md | 45 ++++ 3 files changed, 258 insertions(+) create mode 100644 .archive/2026-05-06-hermes-skills-rollout.md create mode 100644 .wiki/raw/research/hermes-agent-skills/how-to-create.md diff --git a/.archive/2026-05-06-hermes-skills-rollout.md b/.archive/2026-05-06-hermes-skills-rollout.md new file mode 100644 index 0000000..e622994 --- /dev/null +++ b/.archive/2026-05-06-hermes-skills-rollout.md @@ -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/// +├── 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). diff --git a/.wiki/log.md b/.wiki/log.md index 84243d8..7ddc022 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -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 diff --git a/.wiki/raw/research/hermes-agent-skills/how-to-create.md b/.wiki/raw/research/hermes-agent-skills/how-to-create.md new file mode 100644 index 0000000..14de5ab --- /dev/null +++ b/.wiki/raw/research/hermes-agent-skills/how-to-create.md @@ -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, запишу в репозиторий и закоммичу. \ No newline at end of file