0.4.11
Поиск по документации… ⌘K
10 · Руководство пользователя

10. Скиллы

Скилл — это «специализация» агента: набор инструкций, который помогает AstraCode лучше работать в конкретной области (PDF, design review, тестирование, git workflows и т.п.).

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

Что AstraCode «умеет» из коробки

После установки доступны системные скиллы (в ~/.astracode/skills/.system/):

Скилл Зачем
skill-creator Помогает создать новый скилл — спрашивает имя, описание, генерирует scaffold
skill-installer Установить скилл из GitHub-репозитория
astracode-help Подробные ответы на вопросы про AstraCode
astracode-best-practices Стратегии надёжной работы с AstraCode
goal-usage Как правильно вести цели (/goal) с evidence-checks
pdf Читать, создавать, редактировать PDF (визуальная проверка)
doc Работать с .docx файлами (через python-docx)
humanizer Убирать «следы AI» в тексте (для документов)
playwright Автоматизация браузера через Playwright
web-design-guidelines WCAG 2.2, responsive layout, accessibility
ios-design-guidelines Apple HIG для iPhone (SwiftUI / UIKit)
macos-design-guidelines Apple HIG для Mac (AppKit, меню, shortcuts)

Это «навыки в спящем режиме» — они в файловой системе, но не загружены в контекст модели, пока не активируются. Это экономит токены.

Как активируется скилл

Тремя способами:

1. Явно от вас — $<skill-name>

В composer'е введите $ и выберите скилл:

text
> $skill-c_
  ┌──────────────────────────────────┐
  │ skill-creator    — Создать ск…  │
  │ skill-installer  — Установить…  │
  └──────────────────────────────────┘

При выборе в строку ввода вставляется упоминание скилла — $skill-creator. Допишите свою задачу (или просто нажмите Enter) — и при отправке скилл активируется: его SKILL.md целиком попадает в контекст, и модель начинает работать с учётом этих инструкций.

text
> $skill-creator помоги собрать новый скилл

2. Через меню /skills

text
/skills

Откроется меню из двух пунктов (в русской локали): - Открыть список Skills — то же, что ввести $: список установленных скиллов для выбора. Само по себе меню скиллы не устанавливает. - Включить/выключить Skills — экран с переключателями вкл/выкл для каждого скилла (постоянно).

3. Автоматически (implicit invocation)

Многие скиллы умеют активироваться сами, когда видят релевантное действие:

  • Запустили python scripts/foo.py → активируется скилл, у которого есть этот scripts/.
  • Прочитали references/api.md → активируется скилл с этим референсом.

Контролируется флагом allow_implicit_invocation в секции policy файла agents/astracode.yaml скилла. По умолчанию — true.

Что происходит когда скилл активируется

Содержимое SKILL.md (markdown с инструкциями) попадает в контекст модели. Модель видит:

«Ты используешь скилл pdf. Вот его инструкции: ... [подробный текст про работу с PDF] ...»

Дальше модель работает с учётом этих инструкций. Может вызывать tools, скрипты из scripts/, читать references.

Как поставить новый скилл

Способ 1: skill-installer (из GitHub)

skill-installer — это встроенный скилл-установщик. В строке ввода наберите $skill-installer и активируйте его. Репозиторий не захардкожен — вы каждый раз указываете источник сами. Поддерживаются две формы:

text
# по имени репозитория + путь к папке скилла внутри него:
$skill-installer ... --repo <owner>/<repo> --path <путь/к/папке-скилла>

# или по полному URL c указанием ветки и пути:
$skill-installer ... --url https://github.com/<owner>/<repo>/tree/<ветка>/<путь/к/папке-скилла>

Конкретный пример: публичный репозиторий Anthropic

Реальный публичный репозиторий со скиллами — github.com/anthropics/skills. Скиллы лежат в подпапке skills/ (например skills/pdf/, skills/docx/, skills/pptx/, skills/xlsx/), каждый — в своей папке с SKILL.md.

Установить из него скилл pdf (по имени репозитория + путь к папке скилла):

text
$skill-installer --repo anthropics/skills --path skills/pdf

То же самое через полный URL (с веткой main):

text
$skill-installer --url https://github.com/anthropics/skills/tree/main/skills/pdf

Посмотреть, какие скиллы есть в репозитории, до установки:

text
$skill-installer --repo anthropics/skills --path skills

Что произойдёт при установке: - Установщик скачает папку skills/pdf (по умолчанию — zip-архивом; при ошибке авторизации перейдёт на git). - Проверит, что в ней есть SKILL.md (без него — ошибка). - Скопирует её в ~/.astracode/skills/pdf/. Имя берётся из последнего сегмента пути (--path), то есть pdf, а не из имени репозитория. Переопределить можно флагом --name. - Если такая папка уже есть — установка прервётся (защита от перезаписи).

После установки перезапустите AstraCode, чтобы он подхватил новый скилл.

⚠️ Частые ошибки: - Голый адрес репозитория без пути к папке скилла ($skill-installer https://github.com/anthropics/skills) не сработает — установщик попросит --path. - Поддерживается только домен github.com. - Приватные репозитории — через GITHUB_TOKEN/GH_TOKEN или настроенные git-учётные данные.

Как должен выглядеть репозиторий со скиллами

Жёсткого требования к структуре всего репозитория нет — устанавливается конкретная папка-скилл, на которую указывает --path. Требование одно: в этой папке должен лежать SKILL.md. Раскладка anthropics/skills как образец:

text
anthropics/skills                ← репозиторий на GitHub
└── skills/                       ← каталог со скиллами
    ├── pdf/
    │   ├── SKILL.md              ← обязателен
    │   ├── scripts/
    │   └── references/
    ├── docx/
    │   └── SKILL.md
    └── xlsx/
        └── SKILL.md

То есть: один репозиторий может содержать много скиллов, каждый — в своей подпапке со своим SKILL.md. Если делаете собственный репозиторий, по умолчанию установщик ищет скиллы в каталоге skills/.curated (это можно переопределить флагом --path).

Способ 2: skill-creator (написать свой)

text
$skill-creator

Скилл проведёт через шаги: 1. Имя скилла. 2. Краткое описание (EN и RU). 3. Default prompt (затравка при выборе из picker'а). 4. Что должен делать. 5. (Опционально) скрипты и references.

Сгенерирует структуру под ~/.astracode/skills/<your-skill>/ — готово к использованию.

Способ 3: вручную

bash
mkdir -p ~/.astracode/skills/my-helper
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

После — перезапуск AstraCode (или /skills → обновить), и скилл появится.

Скиллы проекта (только для этого репо)

Если скилл нужен только в одном проекте — кладите его в <repo>/.astracode/skills/:

text
~/myproject/
├── .astracode/
│   └── skills/
│       ├── my-project-skill/
│       │   └── SKILL.md
│       └── another-skill/
└── src/

Эти скиллы видны только когда вы запускаете AstraCode из этого репо. Полезно для специфичных рабочих процессов вашего проекта.

Включить / выключить скилл

text
/skills

→ выбрать Enable/Disable → откроется toggle-экран:

text
┌─ Skills ──────────────────────────────────────────┐
│   ☑ skill-creator       Создать или обновить навык│
│   ☑ skill-installer     Установить скилл из GitHub│
│   ☑ pdf                 Работа с PDF              │
│   ☐ humanizer           Убирать следы AI          │
│   ☑ playwright          Автоматизация браузера    │
│   ...                                              │
│                                                    │
│ Search: > _                                        │
└────────────────────────────────────────────────────┘
Space toggle · Enter confirm · Esc cancel
  • Space — переключить.
  • Введите > и текст — фильтр.
  • При выходе (Esc) — показывается сводка что изменилось.

Изменения сохраняются автоматически. Выключенные скиллы — не видны модели даже в discovery; они не появятся в $-picker'е, не активируются неявно.

Когда какие скиллы включать

Системные — обычно включены все

Они компактные и discovery-only — модель видит только их краткое описание (через short-description), полный текст загружается только при активации. Так что overhead минимален.

Кастомные — по контексту проекта

Если работаете с PDF — pdf обязательно. Если делаете веб — web-design-guidelines. Если на iOS — ios-design-guidelines. Лишние — выключите, чтобы не путать модель.

Не включайте всё подряд

С каждым активным скиллом в discovery растёт system prompt. Это: - Слегка увеличивает токены каждого запроса. - Может слегка размывать фокус модели.

Включайте те, что реально используете в этом проекте.

Где живут скиллы

text
<repo>/.astracode/skills/<name>/        ← проектные, priority 0
~/.astracode/skills/<name>/             ← пользовательские, priority 1
~/.astracode/skills/.system/<name>/     ← системные (встроенные), priority 2

Если в двух местах одно имя — побеждает с меньшим priority (ближайший к проекту).

~/.astracode/skills/.system/ — не редактируйте, его перезаписывают при обновлении AstraCode.

Что внутри скилла

Структура:

text
<skill-name>/
├── SKILL.md              ← обязательно: frontmatter + инструкции
├── agents/
│   └── astracode.yaml    ← UI-метаданные (default_prompt, иконка)
├── scripts/              ← опционально
│   └── do_thing.py
├── references/           ← опционально
│   └── api_docs.md
└── assets/               ← опционально (иконки, изображения)

Скилл может использовать tools (например, для запуска scripts/).

Использование scripts

Если в скилле есть scripts/, модель может их запустить (через exec_command). Например, скилл humanizer имеет scripts/humanize.py — модель запустит его, передаст текст, получит результат.

Approval для exec_command работает как обычно — если у вас workspace-write, скрипт спросит разрешение.

Использование references

В references/ лежат документы (PDF, MD, JSON), которые модель может прочитать при необходимости. Например, скилл ios-design-guidelines имеет references/ios_hig.md — выдержки из Apple HIG.

Модель не загружает их сразу — только когда нужно. Это экономит контекст.

Локализация скиллов

Если у вас locale = "ru", в списке скиллов и в popup'е вы увидите русские описания (если скилл их поддерживает).

Встроенные скиллы — все переведены. Кастомные — зависит от автора. При создании скилла через skill-creator он автоматически попросит русское описание.

Скилл vs MCP-сервер vs tool

Не путайте:

Сущность Что это
Tool Функция, которую модель вызывает (exec_command, apply_patch). Встроено в AstraCode.
MCP-сервер Внешний процесс, который добавляет новые tools (Linear, GitHub, etc.). Подключается в config.toml.
Скилл Markdown-инструкции + опциональные скрипты. Учат модель «как делать X». Активируются по запросу.

Скилл может использовать tools и MCP-серверы — но он не запускает «новых» tools.

Безопасность скиллов

  • Скилл может читать ваш код (через инструкции модели).
  • Если в скилле есть scripts/ — они выполняются с правами sandbox (как любая команда).
  • Будьте осторожны с установкой скиллов из недоверенных источников — skill-installer тянет код из GitHub.

При первом запуске скрипта из скилла приходит approval-диалог — как для любой shell-команды.

Best practices

✓ Включайте только нужные скиллы в текущем проекте.
✓ Используйте skill-creator для быстрого создания собственных.
✓ Кладите проектные скиллы в <repo>/.astracode/skills/ — они переедут с репо.
✓ Пишите хорошее description в SKILL.md — модель использует его, чтобы решать «применять или нет».
✗ Не редактируйте .system/ — перезатрётся при обновлении.
✗ Не пишите большие скиллы — лучше несколько фокусных.
✗ Не сохраняйте секреты в скиллах — они в открытом markdown.

Где узнать больше

Если что-то не работает

  • Скилл не появляется в picker'е — проверьте, что в SKILL.md есть валидный YAML frontmatter с name и description. AstraCode при старте выдаёт warning, если SKILL.md не парсится.
  • YAML-ошибка — если в значении есть :, оборачивайте в кавычки: short-description: "Видимый контекст: правила".
  • Скилл не активируется неявно — проверьте policy.allow_implicit_invocation: true в agents/astracode.yaml.
ESC