Что такое scripts в Agent Skill?
Scripts — необязательные исполняемые файлы внутри пакета навыка. Они выполняют детерминированную операцию, но не запускаются сами: SKILL.md должен явно объяснить, когда и какой командой их вызывать.
Текстовая инструкция направляет рассуждение агента. Script берёт на себя точное преобразование, проверку или сбор фактов, которые не стоит каждый раз воспроизводить заново. Поддерживаемые языки и возможности среды определяет клиент, а не сам формат Agent Skills.
Когда операцию стоит вынести в script?
Используйте script для повторяемого преобразования, строгой валидации, сложной команды или машиночитаемого результата. Оставьте в тексте выбор стратегии, оценку смысла и ситуации, где нужен контекстный judgement.
| Оставить в SKILL.md | Вынести в scripts |
|---|---|
| Выбрать подход по контексту | Проверить схему или обязательные поля |
| Сформулировать редакционный вывод | Преобразовать одинаковый набор файлов |
| Решить, нужно ли подтверждение | Собрать детерминированный отчёт |
| Объяснить границы процесса | Выполнить длинную и часто ошибочную команду |
Если основной файл разросся из-за справочников и повторяемых операций, сначала разделите большой SKILL.md.
Как устроить минимальный пакет со script?
Храните SKILL.md в корне навыка, исполняемые файлы — в scripts, а примеры входов — в отдельной тестовой папке или references. В инструкции используйте относительные пути от корня skill.
- SKILL.md — условия вызова, порядок работы и команда.
- scripts/check-input.js — одна узкая проверяемая операция.
- references/input-schema.md — описание формата и ограничений.
- fixtures/sample.json — обезличенный пример для локального теста.
Избегайте глубокой цепочки ссылок, при которой SKILL.md ведёт в один справочник, тот — во второй, а команда спрятана в третьем. Агент и человек должны быстро увидеть контракт выполнения.
Какой контракт нужен у script?
Опишите вход, выход, коды завершения, побочные эффекты и примеры запуска. Команда должна работать без интерактивного TTY, давать короткий --help и возвращать ошибку, которую можно исправить.
- Вход: аргументы, stdin или документированные переменные окружения.
- Результат: стабильный JSON, CSV, TSV или однозначный текстовый формат.
- stdout: полезные данные для следующего шага.
- stderr: прогресс и диагностика без секретов.
- Exit code 0: операция завершена; ненулевой код: конкретная ошибка.
- Side effects: какие файлы, записи или внешние системы могут измениться.
Как безопасно выполнять изменяющую команду?
Разделите процесс на analyze → plan → validate → execute → verify. До изменения создайте план или preview, проверьте его отдельной командой и только затем выполняйте действие с явным подтверждением.
- 1. Analyze
Прочитать вход и собрать факты без изменения состояния.
- 2. Plan
Сохранить полный список предполагаемых действий.
- 3. Validate
Проверить схему, области, лимиты и запрещённые назначения.
- 4. Execute
Выполнить только подтверждённый план.
- 5. Verify
Сопоставить фактический результат с планом и сохранить evidence.
Для отдельной детерминированной проверки используйте подход validator и доказательства.
Как описать runtime и зависимости?
Укажите интерпретатор, минимальную версию, способ установки и зафиксированные версии зависимостей. Не предполагайте, что Python, Bash, Node.js, сеть или пакетный менеджер доступны во всех клиентах.
Исполняемая среда может быть локальной, контейнерной или удалённой. В одной сети доступ разрешён, в другой пакеты нельзя установить, а в третьей любой shell-вызов требует подтверждения. Эти ограничения должны быть частью compatibility и тестового протокола.
- Предпочитайте стандартную библиотеку для маленьких утилит.
- Фиксируйте версии сторонних пакетов и проверяйте их происхождение.
- Не загружайте код во время исполнения без явной необходимости.
- Добавьте понятную ошибку для отсутствующего runtime.
- Проверяйте путь на Windows, macOS и Linux только там, где заявлена поддержка.
Как проверить разрешения и безопасность script?
Относитесь к script как к стороннему коду: прочитайте его и зависимости, ограничьте файловую систему, сеть и секреты, протестируйте на копии данных и не включайте безусловное автоматическое подтверждение shell.
- Проверьте источник, лицензию, commit и полный diff.
- Найдите чтение env, домашнего каталога, ключей и конфигурации.
- Проверьте сетевые адреса, subprocess и динамическую загрузку.
- Для записи добавьте dry-run, allowlist целей и резервную копию.
- Не передавайте секреты через аргументы и журналы.
- После теста подтвердите, какие файлы или записи действительно изменились.
До первого запуска пройдите чек-лист проверки AI-навыка.
Какие тесты нужны script внутри skill?
Минимум нужны happy path, неверный вход, граничные значения, повторный запуск и режим без побочных эффектов. В CI проверяйте сам файл, ссылки из SKILL.md и фактический exit code команды.
| Проверка | Что подтверждает |
|---|---|
| --help | Команда доступна и интерфейс понятен |
| Валидная фикстура | Результат соответствует зафиксированной схеме |
| Повреждённая фикстура | Ошибка полезна и exit code ненулевой |
| Два одинаковых запуска | Операция идемпотентна либо явно описывает повторный эффект |
| Dry-run и execute | Preview совпадает с реальным набором действий |
Структурные и поведенческие проверки можно объединить в CI для Agent Skills.
Когда script готов к использованию агентом?
Script готов, если решает одну детерминированную задачу, явно вызывается из SKILL.md, имеет стабильный контракт, работает в заявленной среде, ограничивает побочные эффекты и проходит воспроизводимые тесты.
- Есть причина, почему текста инструкции недостаточно.
- Команда и относительный путь приведены дословно.
- Вход, выход, stderr и exit codes документированы.
- Runtime и зависимости зафиксированы.
- Для изменений есть plan, dry-run или preview.
- Права минимальны, секреты не журналируются.
- Фикстуры и проверки запускаются без рабочих данных.
Даже хорошо протестированный script не становится переносимым автоматически. Повторите аудит после смены клиента, runtime, модели или политики разрешений.