Skills

Skills — модульные инструкции для агента, которые расширяют его возможности. Каждый skill — это Markdown-файл с YAML-фронтматером, содержащий целевую задачу, контекст и инструкции.

1. Концепция

Skill — это Markdown-документ с YAML-фронтматером. Когда агент активирует skill, содержимое файла добавляется в системный промпт как специализированные инструкции.

Зачем нужны skills:

• Модульность: логически изолированные инструкции для конкретных задач
• Переиспользование: skills работают в любом проекте
• Самомодификация: агент может создавать и редактировать skills
• Безопасность: project trust контролирует выполнение

2. Типы skills

SOBA различает три типа скилов по их расположению:

Приоритет при конфликте имён

При одинаковых именах: Project > User > Internal > Bundled.

3. Bundled skills

SOBA поставляется с 13 встроенными скилами в директории skills/:

Просмотр 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. Обязательные поля фронтматера

5.3. Создание через мастер

# В TUI запустить интерактивный мастер
/skill new

Мастер запросит:

1. Имя skill
2. Описание
3. Тип (user или project)
4. После создания откроет редактор

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.md

6. Жизненный цикл skill

6.1. Этапы

[Create] → [Edit] → [Review] → [Use]
    ↑                    ↓
    └──── [Revise] ←────┘

1. Create — создание файла skill (через мастер или вручную)
2. Edit — редактирование содержания (/skill edit <name>)
3. Review — агент проверяет skill на корректность
4. Use — агент автоматически или вручную активирует skill
5. Revise — после использования можно улучшить skill

6.2. Eval

Оценка эффективности skill после использования:

# Запустить eval для skill
/skill eval my-skill

# Агент проанализирует результаты использования и предложит улучшения

6.3. Bench и Trace

После eval SOBA сохраняет runs в локальном evaluation storage. Их можно просматривать как skill card:

# Агрегированное качество skill
/skill bench my-skill

# Последние eval runs и failed cases
/skill trace my-skill
/skill trace my-skill --last 5

bench показывает количество runs, success rate, median pass rate, median cases, latest run и common failures. trace показывает последние runs с pass rate и причинами failed cases. Эти команды не запускают модель: они читают уже сохранённые eval artifacts.

Skill eval bench and trace — обязательный цикл для скила, который должен использоваться повторно:

1. /skill eval <name> запускает deterministic evaluation cases и сохраняет локальные artifacts.
2. /skill bench <name> показывает агрегированное качество и common failures.
3. /skill trace <name> раскрывает последние eval runs и failed cases, чтобы следующая правка была точечной.

Не продвигайте project skill в user scope, пока eval, bench и trace не показывают согласованную картину.

6.4. Promote

Продвижение project skill → user skill:

# Project skill, который хорошо себя показал, можно сделать общедоступным
/skill promote my-skill

6.5. 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

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 работает не так, как ожидается:

1. Проверьте описание — агент использует его для решения, когда активировать skill
2. Добавьте примеры — они помогают агенту понять ожидаемый формат
3. Уточните инструкции — делайте их более конкретными
4. Используйте eval/bench/trace — /skill eval <name>, /skill bench <name> и /skill trace <name> для анализа
5. Проверьте контекст — убедитесь, что skill активируется в правильной ситуации