harness/README.md

Harness 🛠️

Универсальный менеджер скиллов, агентов, MCP-серверов и конфигов для Hermes и OpenCode.

Репа-каталог, где живут ссылки на полезные skills, MCP-серверы, тулзы и агенты — с единым скриптом управления.

dev/harness/
├── agents/                     # Определения агентов OpenCode (leader, fixer, devops, admin, ...)
├── catalog/                    # Скиллы: git submodule'ы на внешние репы
│   ├── jakubkrehel-skills/     # → github.com/jakubkrehel/skills (11 скиллов UI)
│   └── developer-documentation-skill/  # → NateBJones-Projects/… (доки; ставится вручную)
├── scripts/
│   └── harness                 # Основной CLI-скрипт
└── README.md

Грамматика

Объект — первым, действие — вторым: harness <объект> <действие> [аргументы]

Объект	Что это	Действия
status	среда целиком	—
skills	скиллы из каталога	list, installed, install, remove
agents	агенты (только OpenCode)	list, install, remove
mcp	MCP-серверы Hermes	list, add, rm
catalog	внешние репозитории каталога	list, update
hermes	сам Hermes	config, restart, update
opencode	сам OpenCode	install, restart

./scripts/harness status
./scripts/harness skills list
./scripts/harness skills install jakubkrehel-skills better-ui --target all
./scripts/harness agents install leader
./scripts/harness mcp list
./scripts/harness catalog update
./scripts/harness hermes restart

Быстрый старт

./scripts/harness status              # Обзор среды
./scripts/harness skills list         # Что доступно в каталоге (+ отметки установки)
./scripts/harness skills installed    # Что реально стоит у агентов
./scripts/harness agents list         # Агенты: доступные в репо + установленные
./scripts/harness mcp list            # MCP-серверы Hermes
./scripts/harness catalog list        # Источники каталога

skills — скиллы из каталога

skills list — что доступно к установке

Показывает содержимое каталога и где скилл уже стоит. ✓ — установлено, · — нет.

./scripts/harness skills list
./scripts/harness skills list --target opencode

Доступно из каталога (/mnt/data/Agent/dev/harness/catalog)
  ✓ — установлено, · — нет

  jakubkrehel-skills  11 скиллов  267330e
    ├─ better-ui                    hermes ·  opencode ✓
    ├─ better-colors                hermes ·  opencode ·
    ...

Для git-источников показывается короткий sha; ⚠ сдвинут — submodule ушёл вперёд и это ещё не закоммичено.

skills installed — что реально стоит

Полное дерево каталогов агента, включая скиллы не из каталога.

./scripts/harness skills installed
./scripts/harness skills installed --target hermes

skills install / skills remove

# Один скилл
./scripts/harness skills install jakubkrehel-skills better-ui --target opencode
./scripts/harness skills install jakubkrehel-skills/better-ui --target all

# Все скиллы источника
./scripts/harness skills install jakubkrehel-skills --all --target opencode

# Удалить
./scripts/harness skills remove better-ui
./scripts/harness skills remove better-ui --target hermes

Скиллы ставятся симлинками:

Агент	Куда ставится
Hermes	~/.hermes/skills/catalog/<name>/
OpenCode	~/.claude/skills/<name>/
OpenCode	~/.config/opencode/skills/<name>/

agents — агенты (только OpenCode)

Источник — harness/agents/*.md. Имя агента = имя файла без .md.

./scripts/harness agents list
./scripts/harness agents list --scope global
./scripts/harness agents list --scope project --project ~/work/myrepo

./scripts/harness agents install leader                # в ~/.config/opencode/agents/
./scripts/harness agents install --all --scope global
./scripts/harness agents install devops --scope project --project ~/work/myrepo

./scripts/harness agents remove leader
./scripts/harness agents remove leader --scope global

--scope	Куда ставится
global (по умолчанию)	~/.config/opencode/agents/<name>.md
project	<project>/.opencode/agents/<name>.md (по умолчанию — cwd)

Ставятся симлинками, так что правки в репе сразу видны OpenCode. Все агенты имеют mode: all (кроме leader — primary), чтобы лидер мог вызывать их как сабагентов.

Hermes агентов не поддерживает — только runtime-делегирование через delegate_task. Пользовательских определений агентов у него нет.

mcp — MCP-серверы Hermes

./scripts/harness mcp list

# По URL (HTTP/SSE)
./scripts/harness mcp add my-server http://localhost:8000/mcp

# Командой (stdio)
./scripts/harness mcp add github npx \
  --env GITHUB_TOKEN=ghp_xxx \
  --arg -y --arg @modelcontextprotocol/server-github

./scripts/harness mcp rm my-server

add и rm сами перезапускают hermes-gateway, чтобы изменения подхватились.

catalog — внешние репозитории

./scripts/harness catalog list     # источники, содержимое, sha, признак «сдвинут»
./scripts/harness catalog update   # git submodule update --remote / git pull для клонов

hermes / opencode — сам агент

./scripts/harness hermes config                        # показать конфиг
./scripts/harness hermes config --set model.default=gpt-4o
./scripts/harness hermes config --set agent.max_turns=200
./scripts/harness hermes restart    # systemctl --user restart hermes-gateway + webui
./scripts/harness hermes update     # hermes update + рестарт сервисов

./scripts/harness opencode install  # curl-установщик opencode.ai
./scripts/harness opencode restart  # systemctl --user restart opencode + openchamber

hermes config --set меняет ~/.hermes/config.yaml и перезапускает сервисы.

Как добавить скилл в каталог

Каталог — это git submodule'ы: в репе фиксируется ссылка на внешний репозиторий и точный коммит, а не копия файлов.

git submodule add https://github.com/user/skills-repo.git catalog/user-skills
git commit -m "chore: add user-skills to catalog"

После этого harness skills list покажет найденные скиллы, а harness catalog update подтянет свежие коммиты во всех submodule'ах.

Раскладка репозитория и ручная установка

CLI понимает одну раскладку — <репа>/skills/<name>/SKILL.md. Репозитории с другой структурой (SKILL.md в корне, .agents/skills/, вложенные категории) он показывает без списка скиллов, и такие скиллы ставятся вручную. Ограничение только у CLI: сам OpenCode сканирует рекурсивно (skills/**/SKILL.md, а через skills.paths — **/SKILL.md на любой глубине).

Пример — developer-documentation-skill держит SKILL.md в корне репы:

ln -s /mnt/data/Agent/dev/harness/catalog/developer-documentation-skill \
      ~/.agents/skills/developer-documentation

Альтернатива без симлинков — указать в конфиге OpenCode корень каталога:

{ "skills": { "paths": ["/mnt/data/Agent/dev/harness/catalog"] } }

Тогда OpenCode найдёт все SKILL.md из каталога, в любой раскладке. Минус — подхватывается всё содержимое разом, включая ненужное.

Как добавить агента

Положить .md файл в agents/ репозитория — и он сразу виден через harness agents list.

Формат — как у OpenCode:

---
description: "Что делает агент и когда его звать"
mode: all            # primary | subagent | all
temperature: 0.1
steps: 100
color: "#2563eb"
permission:
  task: deny
  bash: allow
  edit: allow
---

# Имя агента

Тело промпта: роль, принципы, порядок работы, что НЕ делать, формат ответа.

• mode: all — можно и вызвать напрямую, и делегировать из leader (сабагент).
• mode: primary — только как основной агент (Tab в UI). Такой агент не появится в task-инструменте лидера: OpenCode фильтрует список сабагентов по mode !== "primary".

Поддерживаемые форматы

• Скиллы — SKILL.md с YAML frontmatter (name, description); родной формат OpenCode и Hermes.
• Агенты — <name>.md с frontmatter (description, mode, ...); формат OpenCode.

Совместимость

Фича	Hermes	OpenCode
Skills (SKILL.md)	✅ ~/.hermes/skills/	✅ ~/.claude/skills/, ~/.config/opencode/skills/
Agents	❌ (только delegate_task в рантайме)	✅ ~/.config/opencode/agents/, <project>/.opencode/agents/
MCP-серверы	✅ config.yaml mcp_servers	🟡 через opencode.json
Plugins	✅ .hermes/plugins/	❌ (не поддерживает)
Systemd service	✅ gateway + webui	✅ opencode + openchamber
CLI install/update	hermes update	curl install script