05. Скиллы

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

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

my-skill/
├── SKILL.md                    # обязательный: frontmatter + инструкции
├── agents/
│   ├── astracode.yaml          # UI-метаданные для AstraCode
│   └── openai.yaml             # опционально, для совместимости со старыми конфигами
├── 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-парсер падает.

Важно: имя папки скилла и поле name в SKILL.md должны быть корректны и согласованы — по ним скилл идентифицируется и вызывается через $name. Ошибка в имени приведёт к тому, что скилл не загрузится или не найдётся при вызове.

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 (см. core-skills/src/render.rs). Сам файл SKILL.md целиком в контекст не добавляется:

• При явном упоминании ($skill-name) полное содержимое SKILL.md подставляется в контекст автоматически (core-skills/src/injection.rs, build_skill_injections).
• Без явного упоминания (неявное срабатывание по script/doc-триггеру или по совпадению с описанием) модель видит лишь метаданные и, решив применить скилл, открывает 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 (Python-скрипты в skills/src/assets/samples/skill-installer/scripts/). Захардкоженного репозитория нет — источник задаётся аргументами:

Конкретный пример — установка скилла pdf из реального публичного репозитория github.com/anthropics/skills (скиллы лежат в skills/<name>/):

# по репозиторию + пути к папке скилла:
$skill-installer --repo anthropics/skills --path skills/pdf

# по полному URL (ветка main):
$skill-installer --url https://github.com/anthropics/skills/tree/main/skills/pdf

# посмотреть список скиллов в репозитории до установки:
$skill-installer --repo anthropics/skills --path skills

Поведение скрипта install-skill-from-github.py: - Скачивает указанную папку (download zip через codeload.github.com; при ошибке авторизации — git sparse checkout, при необходимости по SSH). - Требует наличие SKILL.md в папке (_validate_skill), иначе ошибка. - Копирует в $ASTRACODE_HOME/skills/<имя> (по умолчанию ~/.astracode/skills), где <имя> = basename пути из --path (не имя репозитория!); переопределяется флагом --name. - Прерывается, если папка назначения уже существует.

Голый URL без /tree/<ref>/<path> или --repo без --path даёт ошибку Missing --path. Поддерживается только github.com. Листинг доступных скиллов — list-skills.py (по умолчанию каталог skills/.curated). После установки требуется перезапуск AstraCode.

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. Если есть ошибки — выдаёт локализованное предупреждение через 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. Рекомендации

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