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 → нигде (в чат, в задачу).
Ссылки: Официальные скиллы | Документация | Примеры
Hermes Agent: How to Write Custom Skills — From YAML to Triggers
SKILL.md anatomy: YAML frontmatter, description as main trigger, tools for scope, markdown instructions. Examples: git-workflow, test-runner, code-review, deploy-pipeline. Description rules, debugging, best practices. Turn any instruction into a working skill in 5 minutes.
Hermes Agent: How to Write Custom Skills — Complete Guide
A skill in Hermes is a Markdown file with YAML frontmatter, loaded on trigger. This is a new form of code: instructive Markdown with metadata. Let's break down how to turn any instruction into a working skill in 5 minutes.
1. SKILL.md File Anatomy
# .hermes/skills/my-skill.md
---
name: my-skill # unique name (for loading)
description: "Use when..." # trigger for auto-load
tools: [bash, read, write, edit, grep, github] # available tools
model: "anthropic/claude-3.5-sonnet" # optional: custom model
---
# My Skill
## When to use
Description of situations when agent should load this skill.
## Procedure
1. Step 1
2. Step 2
3. Step 3
## Pitfalls
What can go wrong and how to avoid.
## Examples
Usage examples.
2. Description Field — Main Trigger
Agent only sees description before loading skill. Write triggers:
"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"
More specific = more accurate auto-loading. Don't write: "Use for git stuff". Write: "Use when user wants to create a feature branch and open a PR".
3. Tools Field — Scope & Safety
Restrict skill to only needed tools — safety and focus:
[bash, read, write, edit, grep] — basic file ops
[bash, read, write, edit, grep, github] — + GitHub API
[bash, read, write, edit, grep, postgres, mysql] — + databases
[browser, read, write, edit] — web scraping
Don't give extra tools — it's safety and focus.
4. Ready-to-Use Examples (Copy & Adapt)
🔧 git-workflow — Branching, Commits, PRs
---
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 — How to Run Tests in Project
---
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 — Review Checklist
---
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 — Full 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. Where to Store Skills
- Global (all projects):
~/.hermes/skills/
- Project-specific:
.hermes/skills/ in repo root
Agent checks both folders, project ones take priority.
6. Debugging Skills
hermes skills list — list loaded skills
hermes skills show my-skill — skill content
hermes skills validate — validate all skills syntax
hermes logs --skill my-skill — skill execution logs
7. Best Practices
- One skill = one atomic task
- Always write Pitfalls (what can go wrong)
- Test on simple example before production use
- Use specific description for accurate auto-loading
- Limit tools to minimum necessary
- Version skills in git (.hermes/skills/ in repo)
8. Tiny Test: Where to Put?
If needed in every dialogue → memory (user facts).
If only for specific task type → skill (procedure).
If only in this repo → CLAUDE.md (project details).
Temporary TODO → nowhere (in chat, in task).
Links: Official Skills | Documentation | Examples