Hermes Agent: как писать свои скиллы — полное руководство

Скилл в Hermes — это Markdown-файл с YAML-frontmatter, загружаемый по триггеру. Это новая форма кода: инструктивный Markdown с метаданными. Разбираем, как превратить любую инструкцию в работающий скилл за 5 минут.

1. Анатомия SKILL.md файла

# .hermes/skills/my-skill.md
---
name: my-skill                    # уникальное имя (для загрузки)
description: "Use when..."       # триггер для автозагрузки
tools: [bash, read, write, edit, grep, github]  # доступные инструменты
model: "anthropic/claude-3.5-sonnet"  # опционально: своя модель
---

# My Skill

## When to use
Описание ситуаций, когда агент должен загрузить этот скилл.

## Procedure
1. Шаг 1
2. Шаг 2
3. Шаг 3

## Pitfalls
Что может пойти не так и как избежать.

## Examples
Примеры использования.

2. Поле description — решает всё

Агент видит только description до загрузки скилла. Пишите триггеры:

  • "Use when user wants to deploy to production"
  • "Use when code review is needed before commit"
  • "Use when database migration is required"
  • "Use when creating a new PR with tests"
  • "Use when debugging a failing test"

Чем конкретнее — тем точнее сработает автозагрузка. Не пишите: "Use for git stuff". Пишите: "Use when user wants to create a feature branch and open a PR".

3. Поле tools — ограничение и безопасность

Ограничьте скилл только нужными инструментами:

  • [bash, read, write, edit, grep] — базовые файловые операции
  • [bash, read, write, edit, grep, github] — + GitHub API
  • [bash, read, write, edit, grep, postgres, mysql] — + базы данных
  • [browser, read, write, edit] — веб-скрейпинг

Не давайте лишних инструментов — это безопасность и фокус.

4. Готовые примеры (скопируйте и адаптируйте)

🔧 git-workflow — ветвление, коммиты, PR

---
name: git-workflow
description: "Use when working with git: branching, commits, PRs. Without it the agent makes chaotic history."
tools: [bash, read, write, edit, grep, github]
---

# Git Workflow

## When to use
Use when user wants to work with git: create branches, commit, push, open PR.

## Procedure
1. Check current branch: git branch
2. Create feature branch: git checkout -b feature/{name}
3. Make changes
4. Stage: git add .
5. Commit: git commit -m "feat: {description}"
6. Push: git push origin feature/{name}
7. Create PR: gh pr create --title "{title}" --body "{template}"
8. Wait for CI: gh pr checks --watch

## Pitfalls
- Don't commit directly to main
- Always run tests before push
- Use conventional commits

## Examples
- "Create branch for new feature"
- "Commit my changes with message"
- "Open PR for this feature"

🧪 test-runner — как запускать тесты в проекте

---
name: test-runner
description: "Use when tests need to be run in the project. Knows commands, flags, environment."
tools: [bash, read, write, edit, grep]
---

# Test Runner

## When to use
Use when user asks to run tests, or when code changes need verification.

## Procedure
1. Detect project type: package.json, Cargo.toml, pyproject.toml, go.mod
2. Run appropriate command:
   - Node.js: npm run test / npm run test:watch
   - Rust: cargo test
   - Python: pytest / pytest -xvs
   - Go: go test ./...
3. Parse output, report failures
4. If failures → suggest fixes

## Pitfalls
- Don't run tests in production
- Use --watch for development
- Check for flaky tests

## Examples
- "Run tests"
- "Run tests for user service"
- "Watch tests while I code"

👀 code-review — чек-лист ревью

---
name: code-review
description: "Use when code review is needed before commit. Checks for bugs, style, security."
tools: [bash, read, write, edit, grep]
---

# Code Review

## When to use
Use when user asks for code review before commit or PR.

## Procedure
You are a senior code reviewer. Focus on:
1. Security vulnerabilities (SQLi, XSS, path traversal, secrets)
2. Performance issues (N+1, unnecessary re-renders, memory leaks)
3. Code style consistency (ESLint, Prettier, project conventions)
4. Test coverage gaps (unit, integration, e2e)
5. Proper error handling (try/catch, Result types)
6. Documentation (JSDoc, README updates)

Be concise. Output format:
- **Critical**: must fix before merge
- **Warning**: should fix
- **Nitpick**: optional improvement
- **Praise**: good patterns noticed

🚀 deploy-pipeline — полный деплой

---
name: deploy-pipeline
description: "Use when deploying to production. Runs full pipeline with rollback."
tools: [bash, read, write, edit, grep, github]
---

# Deploy Pipeline

## When to use
Use when user wants to deploy to production.

## Procedure
1. Run tests: npm run test
2. Build: npm run build
3. Check bundle size: npm run analyze
4. Create GitHub release: gh release create
5. Deploy: npm run deploy
6. Verify health: curl https://myapp.com/health
7. Notify: "Deploy v{version} done!"

Rollback on failure:
- git revert HEAD
- npm run deploy
- Notify: "Rollback done"

Error handling:
- If tests fail → stop, notify "Tests failed"
- If build fails → stop, notify "Build failed"
- If health check fails → auto rollback

5. Где хранить скиллы

  • Глобальные (для всех проектов): ~/.hermes/skills/
  • Проектные (только в этом репо): .hermes/skills/ в корне репо

Агент проверяет обе папки, проектные имеют приоритет.

6. Отладка скиллов

  • hermes skills list — список загруженных скиллов
  • hermes skills show my-skill — содержимое скилла
  • hermes skills validate — проверка синтаксиса всех скиллов
  • hermes logs --skill my-skill — логи выполнения

7. Лучшие практики

  • Один скилл = одна атомарная задача
  • Всегда пишите Pitfalls (что может пойти не так)
  • Тестируйте на простом примере перед использованием в проде
  • Используйте конкретные description для точной автозагрузки
  • Ограничивайте tools минимумом необходимого
  • Версионируйте скиллы в git (папка .hermes/skills/ в репо)

8. Миниатюрный тест: куда положить?

Если это нужно в каждом диалоге → memory (факты о пользователе).
Если только для конкретного вида задач → skill (процедура).
Если только в этом репо → CLAUDE.md (детали проекта).
Временный TODO → нигде (в чат, в задачу).

Ссылки: Официальные скиллы | Документация | Примеры