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

Переносимый навык — это не длинная инструкция для конкретного чата. Это формализованный инженерный процесс: с входными условиями, контрактом инструментов, ограничениями прав, проверяемым результатом и понятным поведением при ошибке.
Зачем переносить навык, а не только промпт
Навык агента — повторяемая процедура, которую AI-агент может выполнить в заданной среде. В ней описано не только «что сделать», но и «как понять контекст», «какие инструменты разрешены», «какие изменения допустимы» и «какими проверками подтвердить результат».
Обычный промпт часто зависит от скрытых предположений: текущей директории, имен инструментов, доступных переменных окружения, уровня разрешений или особенностей конкретного раннера. При переносе эти предположения исчезают, а агент продолжает действовать так, будто они существуют.
Цель переносимости — сохранить инварианты процесса, заменяя только адаптеры среды. Сам процесс должен оставаться узнаваемым в разных агентах: например, сначала прочитать контекст, затем проверить предусловия, внести минимальное изменение, запустить верификацию и сообщить об ограничениях.
Модель переносимого навыка
Удобно разделить навык на пять слоёв:
- Назначение. Какую повторяемую задачу решает навык и когда его следует запускать.
- Контекст. Какие файлы, состояния репозитория, входные данные и решения пользователя нужно прочитать.
- Действия. Последовательность операций с конкретными критериями перехода между шагами.
- Среда. Какие инструменты, команды, права и внешние зависимости нужны хосту.
- Результат. Какие артефакты должны появиться, какие проверки должны пройти и что сообщить пользователю.
Ключевой принцип: инструкция навыка должна описывать протокол, а не внутреннее устройство конкретного агента. Названия команд и API относятся к слою среды; критерии готовности и ограничения — к самому навыку.
Готовая структура навыка агента
Минимальная структура может выглядеть так:
skill-name/
├── SKILL.md
├── references/
│ ├── environment-contract.md
│ └── verification.md
├── scripts/
│ └── check.sh
└── examples/
└── minimal-input.md
Файл SKILL.md должен быть коротким маршрутизатором процесса, а подробности — вынесены в ссылки, которые агент читает только при необходимости.
---
name: portable-review
description: Проверяет изменения по заданному контракту и формирует отчёт.
---
# Назначение
Используй навык, когда нужно проверить набор изменений
и получить воспроизводимый отчёт.
# Вход
- рабочая директория проекта;
- список изменённых файлов или ревизия;
- доступ к командам, перечисленным в environment-contract.md.
# Процесс
1. Прочитай контекст проекта и ограничения среды.
2. Определи фактический набор изменённых файлов.
3. Проверь предусловия и остановись при нарушении.
4. Выполни проверки из verification.md.
5. Сформируй отчёт с фактами, пропусками и ограничениями.
# Ограничения
- Не удаляй файлы без явного разрешения.
- Не публикуй секреты и значения переменных окружения.
- Не заявляй об успешной проверке, если команда не запускалась.
# Результат
Сообщи:
- что проверено;
- какие команды выполнены;
- какие проверки пройдены или пропущены;
- какие ограничения остались.
Это пример структуры, а не универсальный готовый навык. Его нужно адаптировать под конкретный процесс и хост.
Шаг 1. Опишите контракт входа и выхода
Начните с границ, а не с команд. Опишите минимальные входные данные и наблюдаемый результат. Если агенту приходится угадывать, где находится проект, какая ветка активна или что считается успехом, навык уже привязан к конкретному окружению.
Для каждого входа укажите:
- обязателен ли он;
- как проверить его наличие;
- что делать при отсутствии;
- можно ли безопасно продолжить без него.
Для результата задайте проверяемые признаки:
- создан или изменён конкретный артефакт;
- команда проверки завершилась успешно;
- вывод содержит требуемые поля;
- агент явно перечислил непройденные проверки.
Формулировка «проверь проект» непроверяема. Формулировка «получи список изменённых файлов, выполни доступный набор проверок и перечисли команды с кодами завершения» уже задаёт контракт.
Шаг 2. Отделите процесс от адаптера среды
В разных агентах один и тот же ресурс может называться по-разному: терминал, shell, command tool или встроенный исполнитель. Не встраивайте конкретное имя инструмента в каждую инструкцию. Опишите логическую операцию, а соответствие вынесите в контракт среды.
# Логическая операция
ОПЕРАЦИЯ: получить статус рабочего дерева
# Возможные реализации
git status --short
или эквивалентная read-only операция хоста
# Требование к результату
Нужно получить фактический список изменённых файлов
и сохранить его в контексте отчёта.
При этом команды нельзя описывать слишком абстрактно. Агенту нужен хотя бы один безопасный эталонный вариант и правило, что делать, если команда недоступна.
Матрица адаптера
| Логическая возможность | Контракт навыка | Зависимость от хоста |
|---|---|---|
| Чтение файлов | Прочитать только перечисленные пути | Filesystem API или безопасная shell-команда |
| Изменение файлов | Изменить только согласованные цели | Права записи и механизм патча |
| Запуск проверки | Сохранить команду и код завершения | Shell, sandbox, рабочая директория |
| Внешний сервис | Указать обязательность и режим отказа | Сеть, авторизация, доступность сервиса |
Шаг 3. Зафиксируйте права и безопасные команды
Переносимость без модели прав опасна: в одной среде команда только читает данные, а в другой может изменить репозиторий или отправить запрос наружу. Для каждой операции определите уровень риска и необходимое подтверждение.
Начинайте проверку с read-only команд:
# Показать файлы без изменения состояния
pwd
rg --files -g '!*node_modules*' | head -80
# Найти инструкции проекта
rg --files -g 'AGENTS.md' -g 'CLAUDE.md' -g 'README*'
# Показать состояние Git без изменения файлов
git status --short
git diff --stat
Эти команды приведены как безопасный пример для Unix-подобной среды. Перед переносом проверьте наличие rg, особенности shell и ограничения на доступ к каталогам. Конструкция head -80 ограничивает объём вывода, но не заменяет проверку прав.
Команды, которые меняют состояние, должны быть отделены от диагностики:
# Сначала определить цель
git diff -- path/to/file
# Затем запросить или подтвердить изменение
# и только после этого применить точечный патч.
Не включайте в навык команды с неявно широким радиусом действия: рекурсивное удаление, перезапись всего каталога, отправку данных во внешние сервисы или чтение всех переменных окружения. Если такая операция необходима, навык должен явно объяснять цель, область, подтверждение и способ восстановления.
Шаг 4. Сделайте контекст явным
Агенту нужно сообщить порядок чтения контекста. Хороший навык не предполагает, что предыдущая беседа или память хоста доступны в новой среде.
- Определите рабочую директорию.
- Найдите локальные инструкции проекта.
- Прочитайте только инструкции, относящиеся к целевому пути.
- Проверьте состояние репозитория и незакоммиченные изменения.
- Сопоставьте доступные инструменты с контрактом навыка.
- Зафиксируйте найденные ограничения до начала записи.
Если контекст нельзя получить, безопасное поведение — остановиться с диагностикой. Молчаливое продолжение создаёт ложную переносимость: навык «работает» только потому, что агент придумал недостающие условия.
Шаг 5. Добавьте режимы отказа
Переносимость проверяется не только успешным сценарием. В новом хосте может отсутствовать команда, быть запрещена запись, не хватать сетевого доступа или отличаться формат вывода.
| Ситуация | Правильная реакция навыка | Что записать в отчёт |
|---|---|---|
| Нет обязательного инструмента | Остановиться или использовать явно разрешённую замену | Имя возможности и причина остановки |
| Нет прав записи | Перейти в режим анализа | Какие изменения не применены |
| Неясна цель изменения | Запросить уточнение | Какое решение требуется от пользователя |
| Проверка завершилась ошибкой | Не объявлять результат успешным | Команда, код и краткий вывод |
| Формат среды отличается | Использовать адаптер или остановиться | Какой контракт не совпал |
Практический план проверки переносимости
Проверяйте навык в двух или более средах, но сравнивайте не внутренние вызовы, а наблюдаемый результат. Если у вас есть только одна среда, можно начать с искусственной проверки: отключить необязательный инструмент, изменить рабочую директорию или запустить навык в режиме только чтения.
1. Зафиксируйте эталонный сценарий
Подготовьте небольшой, безопасный вход:
scenario/
├── input/
│ ├── instructions.md
│ └── sample.txt
├── expected/
│ └── result-contract.md
└── README.md
Эталон должен содержать только данные, нужные для проверки процесса. Не включайте настоящие секреты, клиентские данные или внешние идентификаторы.
2. Запишите инварианты
Составьте список того, что должно совпасть во всех средах:
- прочитан один и тот же набор входных данных;
- изменены только разрешённые файлы;
- применён один и тот же порядок проверок;
- результат содержит одинаковые обязательные поля;
- при недоступной зависимости агент корректно остановился.
3. Сравните возможности хостов
Для каждой среды заполните таблицу: чтение, запись, shell, сеть, секреты, текущая директория, лимиты времени и формат результата. Не приравнивайте наличие инструмента к разрешению на его использование.
4. Прогоните успешный и отказоустойчивый сценарии
Минимальный набор — обычный вход, отсутствующая необязательная зависимость, запрет записи и неоднозначный запрос. Результат каждого прогона сохраняйте как текстовый отчёт с идентификатором среды и датой запуска.
5. Проверьте дифф и отчёт
После выполнения убедитесь, что:
git status --short
git diff --stat
git diff --check
Команда git diff --check проверяет распространённые проблемы пробелов в изменениях; она не доказывает корректность логики. Если навык работает не с Git, используйте эквивалентную проверку списка изменённых артефактов.
6. Разделите несовместимость и ошибку навыка
Если результат отличается, сначала определите источник: неверный процесс, отсутствующая возможность хоста или различие формата. Исправляйте навык только после такой классификации. Иначе инструкция быстро обрастает обходами для одной среды и теряет переносимость.
Типовые ошибки
Скрытая зависимость от предыдущего диалога
Инструкция говорит «продолжи с прошлого шага», но не описывает, где находится его результат. Решение — сохранять промежуточные артефакты в явном месте или повторно получать контекст проверяемой командой.
Смешение политики и механики
Политика определяет, что разрешено: например, не публиковать данные. Механика описывает, как выполнить операцию. Смешивание делает правило трудно переносимым и затрудняет аудит.
Проверка по словам агента
Фраза «проверка пройдена» не является доказательством. Требуйте команду, код завершения, проверенный путь или иной наблюдаемый факт.
Неполный контракт инструментов
Запись «нужен доступ к файлам» недостаточна. Уточните: чтение или запись, какие пути, нужны ли симлинки, допустима ли сеть, какой формат ошибок ожидается.
Слишком много обязательной документации
Если агент должен прочитать десятки страниц до первого действия, навык становится хрупким. Оставьте в основном файле маршрут и критерии, а справочные материалы подключайте по условию.
Ограничения переносимости
Полной переносимости не существует: права, файловая система, сетевые политики, модели безопасности и доступные инструменты различаются. Поэтому корректнее говорить о переносимости по контракту.
Навык переносим, если его инварианты сохраняются, а различия среды явно обнаруживаются и обрабатываются. Если хост не может предоставить обязательную возможность, правильный результат — диагностированная несовместимость, а не попытка обойти ограничение.
Отдельно учитывайте разницу между детерминированными и вероятностными частями. Формат отчёта, список проверок и права можно сделать строгими; формулировки объяснения могут отличаться. В тесте сравнивайте обязательные поля и факты, а не дословный текст ответа.
Итоговый чек-лист
- Назначение навыка сформулировано одним предложением.
- Входы, выходы и критерии успеха проверяемы.
- Процесс отделён от названий инструментов хоста.
- Права чтения, записи и внешних вызовов описаны явно.
- Есть безопасный режим остановки при нехватке возможностей.
- Команды имеют ограниченную область действия.
- Примерные команды помечены как примеры и не выдают их за универсальные.
- Проверены успешный сценарий и несколько отказов.
- Отчёт содержит факты, а не только итоговое утверждение агента.
- Ссылки на подробные инструкции и термины ведут к стабильным страницам.