# Skills и toolsets

`iola-cli` использует skills как подключаемые инструкции для работы с данными городского округа "Город Йошкар-Ола".

Skills не подмешиваются в каждый запрос целиком. CLI выбирает их по смыслу:

- `open-data` - когда запрос про открытые данные, школы, детские сады, адреса, ИНН, слои;
- `reports` - когда нужен отчет, выгрузка, CSV/XLSX или проверка качества;
- `local-files` - когда пользователь просит работать с локальными файлами, папками, архивами или документами;
- `browser-agent` - когда запрос связан с сайтом, URL, страницей, скриншотом или браузером;
- `local-model` - инструкции для локальных компактных моделей и tool-планирования;
- `yandex-services` - когда запрос связан с Yandex Connector или Yandex Cloud Connector: Яндекс Диск, Почта, Календарь, Контакты, Телемост, Yandex ID, геокодер, YandexGPT или Яндекс Go deeplink;
- `user-skills` - когда пользователь просит создать, включить, выключить или удалить собственный skill.

Обычный диалог вроде `привет` не получает инструкции про слои, отчеты, файлы и браузер.

```bash
iola skills list
iola skills show open-data
iola skills create mail-digest --description "Сводка почты" --instructions "Когда пользователь просит сводку почты, найди непрочитанные письма и кратко сгруппируй их по отправителям." --allowed-tools yandex_mail_list,yandex_mail_read --enable
iola skills enable reports
iola skills disable local-model
iola skills delete mail-digest --yes
iola skills paths
```

Папки skills:

- встроенные skills внутри npm-пакета;
- пользовательские skills в `~/.iola/skills`;
- проектные skills в `.iola/skills`.

Toolsets управляют группами разрешений:

```bash
iola tools toolsets
iola tools enable reports
iola tools disable sync
iola tools profile safe
iola tools profile full
```

Режим `safe` подходит для чтения и анализа без записи файлов и без запуска sync.
Режим `full` предназначен для доверенного локального пользователя.

## Пользовательские skills

Пользователь может создавать собственные skills без редактирования npm-пакета. Такие skills сохраняются локально в `~/.iola/skills/<name>/SKILL.md` и не пропадают при обновлении CLI.

Skill - это инструкция для агента, а не произвольный исполняемый код. Он может описывать любые сценарии, но должен опираться на встроенные tools `iola-cli`: открытые данные, Яндекс Почту/Диск/Календарь/Контакты, локальные файлы, browser runtime, cron, MCP, отчеты и память.

Доступные tools управления:

- `user_skill_list` - список пользовательских skills;
- `user_skill_create` - создать skill;
- `user_skill_update` - обновить существующий skill;
- `user_skill_templates` - показать готовые шаблоны;
- `user_skill_preview` - показать будущий `SKILL.md` до записи;
- `user_skill_validate` - проверить структуру и безопасность skill;
- `user_skill_enable` - включить skill;
- `user_skill_disable` - выключить skill;
- `user_skill_delete` - удалить пользовательский skill.

При создании через AI пользователь может написать обычным языком: `создай скилл, который при просьбе "сводка почты" берет непрочитанные письма и группирует по отправителям`. CLI создаст локальный `SKILL.md` и включит его.

Команды:

```bash
iola skills templates
iola skills preview family --template family-calendar
iola skills create family --template family-calendar --enable
iola skills validate family
iola skills update family --instructions "..."
iola skills delete family --yes
```

Для опасных действий внутри пользовательского skill нужно явное подтверждение пользователя: отправка писем, удаление данных, публикация ссылок, запись файлов и изменение внешних сервисов.

## Yandex toolset

Toolset `yandex` включает локальные tools для пользовательских сервисов Яндекса:

- Yandex ID: профиль, логин, email;
- Яндекс Диск: список, создание папок, поиск, сохранение текста, загрузка, скачивание, публичные ссылки;
- Яндекс Почта: статус, список писем, поиск, чтение, отправка;
- Яндекс Календарь: календари, список, поиск, создание, перенос, редактирование, повторы, напоминания, удаление событий;
- Яндекс Документы / 360: работа через Яндекс Диск - список, поиск, создание текстовых документов, чтение, ссылка/QR, переименование, удаление;
- Яндекс Контакты: статус, список, поиск, карточка, создание, обновление, удаление, импорт/экспорт, дубликаты, неполные карточки, backup на Диск, дни рождения в календарь, письмо/ссылка/встреча по контакту;
- Комбинированные сценарии: пакет по письму, полный пакет по контакту, ежедневный дайджест, календарные напоминания, аудит Яндекс Диска;
- Телемост: попытка прямого API и fallback через календарное событие, если API недоступен аккаунту.

Опасные действия ограничены: отправка письма, удаление файлов, публикация ссылок, создание/изменение документов и создание/изменение/удаление событий требуют явного подтверждения в tool-вызове. Токены хранятся локально в `~/.iola/secrets.json`.
