Skills
Bundled, user и project скилы. Создание, редактирование, eval и revision history.
Skills — модульные инструкции для агента, которые расширяют его возможности. Каждый skill — это Markdown-файл с YAML-фронтматером, содержащий целевую задачу, контекст и инструкции.
1. Концепция
Skill — это Markdown-документ с YAML-фронтматером. Когда агент активирует skill, содержимое файла добавляется в системный промпт как специализированные инструкции.
Зачем нужны skills:
- Модульность: логически изолированные инструкции для конкретных задач
- Переиспользование: skills работают в любом проекте
- Самомодификация: агент может создавать и редактировать skills
- Безопасность: project trust контролирует выполнение
2. Типы skills
SOBA различает три типа скилов по их расположению:
| Тип | Расположение | Область действия |
|---|---|---|
| Bundled | skills/ (в дистрибутиве SOBA) | Доступны всегда, во всех проектах |
| Internal | .soba/skills/ (в проекте SOBA) | Для разработки самого SOBA |
| User | ~/.soba/skills/ | Пользовательские, доступны во всех проектах |
| Project | .soba/skills/ (в корне проекта) | Только в рамках конкретного проекта |
Приоритет при конфликте имён
При одинаковых именах: Project > User > Internal > Bundled.
3. Bundled skills
SOBA поставляется с 13 встроенными скилами в директории skills/:
| Skill | Назначение |
|---|---|
| bug-fix | Диагностика и исправление конкретного бага с воспроизведением, минимальным fix и проверкой результата |
| code-review | Review-режим: поиск багов, регрессий, рисков и пробелов в тестах |
| codebase-orientation | Быстрое знакомство с незнакомым репозиторием: структура, entry points, команды и риски |
| commit-message | Генерация conventional commit message по staged changes |
| context-handoff | Подготовка compact handoff-summary для продолжения работы другой сессией или агентом |
| feature-implementation | Реализация feature end-to-end: контекст, план, код, тесты, проверка |
| fix-until-green | Доведение проекта до зелёных проверок, начиная с фактического failure output |
| git-summary | Сводка по git-истории: коммиты, ветки, периоды и изменения |
| lint-fix | Исправление ошибок линтера/форматтера через команды, принятые в текущем проекте |
| memory-capture | Извлечение устойчивых project facts и предложений для Project Memory |
| pr-description | Подготовка PR description по diff, коммитам, тестам и рискам |
| test-authoring | Написание или расширение тестов по user-facing сценариям и edge cases |
| version-bump | Bump версии и связанные release-правки по conventions текущего проекта |
Просмотр bundled skills
# В TUI
/skill list
# Bundled skills отмечены как [bundled]4. Создание своего skill
4.1. Структура файла skill
Каждый skill — это Markdown-файл (.md) с YAML-фронтматером:
---
name: my-custom-skill
description: Краткое описание (1-2 предложения), объясняющее что делает skill и когда его использовать
---
# My Custom Skill
## Context
Описание контекста, в котором skill полезен.
## Instructions
Конкретные инструкции для агента. Что делать, какие шаги выполнять.
## Examples (опционально)
Примеры использования.
## Notes (опционально)
Дополнительные заметки и предостережения.5.2. Обязательные поля фронтматера
| Поле | Описание |
|---|---|
name | Уникальное имя skill (kebab-case) |
description | Краткое описание. Показывается в /skill list и используется агентом для определения, когда активировать skill |
5.3. Создание через мастер
# В TUI запустить интерактивный мастер
/skill newМастер запросит:
- Имя skill
- Описание
- Тип (user или project)
- После создания откроет редактор
5.4. Ручное создание
# User skill (доступен во всех проектах)
mkdir -p ~/.soba/skills
$EDITOR ~/.soba/skills/my-skill.md
# Project skill (только для текущего проекта)
mkdir -p .soba/skills
$EDITOR .soba/skills/my-skill.md6. Жизненный цикл skill
6.1. Этапы
[Create] → [Edit] → [Review] → [Use]
↑ ↓
└──── [Revise] ←────┘- Create — создание файла skill (через мастер или вручную)
- Edit — редактирование содержания (
/skill edit <name>) - Review — агент проверяет skill на корректность
- Use — агент автоматически или вручную активирует skill
- Revise — после использования можно улучшить skill
6.2. Eval
Оценка эффективности skill после использования:
# Запустить eval для skill
/skill eval my-skill
# Агент проанализирует результаты использования и предложит улучшения6.3. Promote
Продвижение project skill → user skill:
# Project skill, который хорошо себя показал, можно сделать общедоступным
/skill promote my-skill6.4. Revision History
SOBA сохраняет историю изменений skill'ов:
# Просмотр истории изменений
/skill history my-skill
# Откат к предыдущей версии
/skill rollback my-skill <revision-id>7. Активация и использование
7.1. Автоматическая активация
Агент автоматически активирует skill, когда задача пользователя соответствует описанию skill.
Например, при запросе "сгенерируй git summary" агент активирует git-summary.
Агент видит список доступных скилов в системном промпте (название + описание).
7.2. Ручная активация
# В TUI
/skill:git-summary
# Агент получит содержимое skill в следующем запросе7.3. Деактивация
Skill активен только в рамках одного запроса. После завершения ответа агента skill автоматически деактивируется (не остаётся в системном промпте).
8. Slash-команды для skills
| Команда | Действие |
|---|---|
/skill list | Показать все доступные скилы |
/skill new | Создать новый скил |
/skill edit <name> | Редактировать существующий скил |
/skill remove <name> | Удалить скил |
/skill:<name> | Активировать скил (через двоеточие) |
/skill eval <name> | Оценить эффективность скила |
/skill promote <name> | Продвинуть project → user |
/skill history <name> | История изменений |
/skill rollback <name> <revision-id> | Откатить к предыдущей версии |
9. Project Trust
При первом использовании project или user skill в проекте SOBA запрашивает подтверждение (project trust):
┌──────────────────────────────────────────────────────────┐
│ ⚠️ Skill "my-custom-skill" is not trusted yet │
│ │
│ Source: ~/.soba/skills/my-custom-skill.md │
│ │
│ Review skill content? [y/N] │
│ Approve for this project? │
│ [A]pprove once [T]rust always [B]lock [C]ancel │
└──────────────────────────────────────────────────────────┘- Approve once — разрешить один раз (следующий вызов снова запросит)
- Trust always — добавить в trusted для этого проекта
- Block — заблокировать skill в этом проекте
- Cancel — отменить использование
Bundled skills всегда доверенные и не требуют подтверждения.
10. Лучшие практики
10.1. Хороший skill
- Узкая специализация: один skill — одна задача
- Чёткие инструкции: агент должен точно понимать, что делать
- Примеры: показывают ожидаемый результат
- Контекст: объясняет, когда skill полезен
10.2. Пример хорошего skill
---
name: generate-changelog
description: Генерирует CHANGELOG.md из git-истории с группировкой по типам изменений (feat, fix, refactor, docs)
---
# Generate Changelog
## Context
Используй после завершения релиза или перед созданием тега.
Требует git-репозиторий с conventional commits.
## Instructions
1. Прочитай `git log` с последнего тега
2. Сгруппируй коммиты по типу (feat, fix, refactor, docs, chore)
3. Для каждого типа создай секцию в CHANGELOG.md
4. Используй формат: `- commit description (hash)`
5. Если CHANGELOG.md существует, добавь новую версию сверху
6. Проверь, что нет дубликатов
## Examples
### Input
git log v1.0.0..HEAD --oneline
a1b2c3d feat: add user authentication
d4e5f6g fix: resolve login timeout
g7h8i9j docs: update API reference
### Output (CHANGELOG.md)
## [1.1.0] - 2024-01-15
### Features
- add user authentication (a1b2c3d)
### Bug Fixes
- resolve login timeout (d4e5f6g)
### Documentation
- update API reference (g7h8i9j)10.3. Отладка skills
Если skill работает не так, как ожидается:
- Проверьте описание — агент использует его для решения, когда активировать skill
- Добавьте примеры — они помогают агенту понять ожидаемый формат
- Уточните инструкции — делайте их более конкретными
- Используйте eval —
/skill eval <name>для автоматического анализа - Проверьте контекст — убедитесь, что skill активируется в правильной ситуации