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.md полностью попадает в контекст). - В composer вставляется default_prompt скилла — текст-затравка (если он задан; есть не у всех скиллов, например у skill-creator/skill-installer его нет).

Например, выбрав doc, увидите:

text
> Edit or review this .docx file and return the updated file plus a concise change summary.

Нажмите Enter — модель начнёт работать по этому промпту с подключённым скиллом.

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

text
/skills

Откроется меню: - List skills — picker всех установленных, как $. - Enable/Disable — toggle'ы для каждого скилла (постоянное вкл/выкл).

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

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

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

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

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

Содержимое SKILL.md (markdown с инструкциями) попадает в контекст модели. В список доступных скиллов (для discovery) модель видит description скилла — то есть то поле, что вы указали в YAML frontmatter. short-description / short-description-ru — это метаданные для UI (picker'а и popup'ов), они в системный промпт не попадают.

Модель видит примерно:

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

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

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

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

В composer:

text
$skill-installer https://github.com/user/my-skill-repo

Скилл скачается в ~/.astracode/skills/<repo-name>/ и сразу доступен.

Способ 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) — показывается сводка что изменилось.

Структура скилла

Типичный скилл:

text
my-skill/
├── SKILL.md               ← главный файл (frontmatter + инструкции)
├── agents/
│   └── astracode.yaml     ← (опционально) policy, default_prompt
├── scripts/               ← опционально
│   └── do_thing.py
├── references/           ← опционально
│   └── api_docs.md
└── assets/               ← опционально (иконки, изображения)

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

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

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

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

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

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

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

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

Если у вас 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.

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

  • /help skills — справка про команду /skills.
  • $astracode-help — встроенный скилл-справочник.

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

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