05. Скиллы

Скилл — это модульный пакет с инструкциями и опциональными скриптами/референсами, который агент может загрузить по запросу или автоматически. Скиллы изолированы: их содержимое не попадает в контекст модели до момента активации.

1. Структура скилла на диске

my-skill/
├── SKILL.md                    # обязательный: frontmatter + инструкции
├── agents/
│   ├── astracode.yaml          # UI-метаданные для AstraCode
│   └── openai.yaml             # legacy, для совместимости с OpenAI SDK
├── scripts/                    # опционально: скрипты, которые скилл может запускать
│   └── do_thing.py
├── references/                 # опционально: документы/PDF/MD для чтения
│   └── api_spec.md
└── assets/                     # опционально: иконки, изображения
    ├── icon-small.svg
    └── icon.png

2. SKILL.md

---
name: my-skill
description: "Подробное описание (до 1024 символов). Это видит модель."
metadata:
  short-description: "Brief one-liner (EN)"
  short-description-ru: "Краткое описание для русского UI"
---

# my-skill

Подробные инструкции и примеры использования.

## When to use

Когда пользователь просит конвертировать markdown в PDF, или …

## Resources

- `scripts/convert.py` — скрипт конвертации
- `references/style_guide.md` — гайд по стилю

Ограничения длины: - name: 64 символа - description: 1024 символа - short-description / short-description-ru: 1024 символа

Важно по YAML: значения с двоеточием обязательно оборачивать в кавычки:

short-description-ru: "Видимый модели контекст: правила работы с историей"

Иначе YAML-парсер падает (раз был такой баг на скилле code-review-context).

3. agents/astracode.yaml

interface:
  display_name: "Создать или обновить навык"
  short_description: "Create or update a skill"
  short_description_ru: "Создать или обновить навык"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon.png"
  brand_color: "#4F46E5"
  default_prompt: "Help me build a new skill"

policy:
  allow_implicit_invocation: true

default_prompt — текст, который вставляется в composer, когда пользователь выбирает скилл из меню.

4. Локализация описаний (RU)

В UI AstraCode описания подбираются по локали через skill_description(&SkillMetadata, TuiLocale):

RU выбран → берётся interface.short_description_ru,
           иначе короткое short_description_ru из SKILL.md,
           иначе short_description (EN),
           иначе description.

То же для EN, только зеркально без RU-ветки.

Поля поддерживаются на трёх уровнях: 1. SKILL.md → metadata.short-description-ru 2. agents/astracode.yaml → interface.short_description_ru 3. Корневой short_description_ru в SkillInterface (legacy).

5. Приоритеты загрузки

AstraCode сканирует скиллы из нескольких мест в порядке убывания приоритета (меньше = выше):

Также сканируется ~/.agents/skills/ для совместимости со старым OpenAI SDK.

При конфликте имён выбирается скилл с меньшим приоритетом (более локальный).

6. Активация скилла

Явная (от пользователя): - В composer: $skill-name или меню через /skills. - Default prompt из agents/astracode.yaml подставится автоматически.

Неявная (от агента): Если policy.allow_implicit_invocation = true (по умолчанию), скилл активируется автоматически: - Script trigger: команды python scripts/foo.py, bash scripts/bar.sh → ищется скилл, у которого этот файл лежит в scripts/. - Doc trigger: чтение references/api.md, references/spec.pdf → ищется скилл с этим референсом.

При активации SKILL.md загружается полностью в контекст.

7. Встроенные системные скиллы

Все системные скиллы переведены — содержат short_description_ru в agents/astracode.yaml.

8. Создание собственного скилла

Самый простой путь — позвать skill-creator:

$skill-creator

Скилл проведёт через шаги: имя, описание, default_prompt, иконка, RU-описание, scripts/references.

Вручную:

mkdir -p ~/.astracode/skills/my-helper/{scripts,references,assets}
cat > ~/.astracode/skills/my-helper/SKILL.md << 'EOF'
---
name: my-helper
description: "Помогает с задачами X, Y, Z."
metadata:
  short-description: "Helper for X/Y/Z"
  short-description-ru: "Помощник по задачам X, Y, Z"
---

# my-helper

Подробные инструкции для агента.
EOF

cat > ~/.astracode/skills/my-helper/agents/astracode.yaml << 'EOF'
interface:
  display_name: "X/Y/Z helper"
  short_description_ru: "Помощник по X/Y/Z"
  default_prompt: "Помоги мне с X"
policy:
  allow_implicit_invocation: true
EOF

После перезапуска TUI (или /skills → refresh) скилл появится в списке.

9. Установка из GitHub

Через скилл skill-installer:

$skill-installer https://github.com/<user>/<repo-with-SKILL.md>

Поставит в ~/.astracode/skills/<repo-name>/.

10. Загрузка и валидация

Loader находится в astracode-rs/core-skills/src/loader.rs. На старте AstraCode:

1. Сканирует все источники.
2. Парсит SKILL.md (frontmatter + body).
3. Парсит agents/astracode.yaml (через serde_yaml).
4. Валидирует длины полей, корректность ссылок на assets.
5. Если есть ошибки — выдаёт локализованный warning через emit_skill_load_warnings() (в startup_prompts.rs).

Известные паттерны ошибок (с RU-переводом): - invalid YAML: ... → невалидный YAML: ... - missing field \...`→отсутствует поле `...`-metadata.short-description-ru is too long (...)`

11. Где какие типы определены

• Core: astracode-rs/core-skills/src/model.rs (SkillMetadata, SkillInterface, Skill)
• Loader: astracode-rs/core-skills/src/loader.rs
• Protocol: astracode-rs/protocol/src/protocol.rs (для сериализации в TUI/RPC)
• TUI helpers: astracode-rs/tui/src/skills_helpers.rs (skill_description)
• TUI integration: astracode-rs/tui/src/chatwidget/skills.rs

12. Best practices

• Короткое description: модель использует его для решения «применять или нет». Чётко, конкретно, без воды.
• Поднимай scripts/ только когда они действительно нужны — каждый файл при активации скилла увеличивает контекст.
• default_prompt должен быть утверждением задачи, а не вопросом («Помоги мне сделать X», а не «Хочешь сделать X?»).
• Локализуй short_description_ru — оно показывается в UI при locale = "ru".
• Тестируй: /skills → выбрать скилл → проверь, что описание корректно.