Что значит «переносимый script»?
Это script с одинаковым документированным интерфейсом и результатом во всех заявленных средах. Он не предполагает конкретную оболочку, текущую папку, разделитель пути или заранее установленную неописанную зависимость.
Необязательно поддерживать каждую ОС. Честный вариант «проверено на Linux, для Windows нужен WSL» полезнее, чем формальное «cross-platform» без тестов. Сначала определите минимальную матрицу: ОС, архитектура, runtime, shell и наличие сети.
Общий ответ на вопрос, когда операция вообще должна стать кодом, дан в статье Scripts в Agent Skill.
Как выбрать общий runtime?
Выбирайте runtime, который уже есть или может быть воспроизводимо установлен во всех целевых средах. Версию и зависимости фиксируйте в compatibility и в самой команде запуска.
| Вариант | Когда подходит | Что проверить |
|---|---|---|
| Python | Обработка файлов и данных | Имя команды, версия, кодировка, зависимости |
| Node.js | JSON, API и существующий JS-стек | Версия, package mode, lockfile или pinned package |
| Deno / Bun | Самодостаточный TypeScript при известной среде | Наличие runtime и сетевые разрешения |
| Bash / PowerShell | Короткая системная автоматизация одной платформы | Явно ограниченная совместимость или отдельный wrapper |
Официальная рекомендация Agent Skills — фиксировать версии одноразовых пакетов и выносить сложную команду в тестируемый script. Автоматическая загрузка зависимости удобна, но означает требование к сети и реестру пакетов, которое тоже нужно декларировать.
Как работать с путями без привязки к ОС?
Стройте путь библиотекой runtime от корня skill, не склеивайте строки с `/` или `\` и не полагайтесь на текущую директорию процесса.
- Передавайте входной и выходной путь аргументами.
- Разрешайте пробелы и Unicode в именах папок.
- Нормализуйте путь перед проверкой границы рабочей директории.
- Не используйте абсолютный путь автора в SKILL.md.
- Проверяйте Windows drive letters, UNC и POSIX root только если заявляете их поддержку.
В Node.js поведение модуля path зависит от платформы, а для явной обработки чужого формата есть path.win32 и path.posix. В Python pathlib различает concrete и pure paths. Такие библиотеки делают различия видимыми и тестируемыми.
Какие ошибки дают shell, кодировка и окончания строк?
Bash-синтаксис не является PowerShell-синтаксисом, executable bit не переносится как Windows-команда, а CRLF может сломать shebang. Поэтому общий script лучше запускать прямой командой runtime, а текстовые правила фиксировать в репозитории.
| Риск | Практическое решение |
|---|---|
| Разное экранирование shell | Передавать аргументы массивом или через CLI-библиотеку, не собирать строку команды |
| CRLF / LF | Зафиксировать правила в .gitattributes; для shell использовать LF |
| Неисполняемый файл | Документировать запуск через runtime, например python script.py |
| Локальная кодировка | Читать и писать UTF-8 явно |
| Разные имена команд | Использовать wrapper или обнаружение с понятной ошибкой |
Какой интерфейс удобен AI-агенту?
Неинтерактивный CLI принимает flags, stdin или environment, показывает короткий --help, возвращает структурированные данные в stdout, диагностику в stderr и различимые exit codes.
- Никаких TTY-вопросов, диалогов выбора и скрытого ожидания пароля.
- Одинаковые имена flags во всех средах.
- JSON или другой однозначный формат для результата.
- Progress и warnings только в stderr.
- Ненулевой exit code для отказа, invalid input и отсутствующей зависимости.
- --dry-run для stateful и потенциально разрушительных операций.
- Повторный запуск не повреждает уже созданный результат.
Как доказать переносимость?
Запустите одну и ту же команду на каждой заявленной ОС в чистой среде. Проверяйте не только успех, но и пробелы в пути, Unicode, отсутствие сети, неверный ввод и повторный запуск.
- 1. Соберите fixtures
Маленький нормальный пример, пустой ввод, повреждённый файл и путь с пробелом и кириллицей.
- 2. Запустите матрицу
Windows, macOS и Linux только в тех версиях, которые обещаны пользователю.
- 3. Сравните контракт
Exit code, JSON-схема, созданные файлы и диагностические сообщения должны иметь одинаковый смысл.
- 4. Зафиксируйте evidence
Версии ОС и runtime, hash пакета, команда и ссылка на успешный run.
Для построения поведенческих тестов используйте методику как тестировать Agent Skill.
Чек-лист перед публикацией script
Публиковать можно после фиксации runtime, зависимостей, путей, формата вывода и проверенной матрицы; неподдерживаемые среды должны быть названы прямо.
- Команда запуска относительна корню skill.
- Нет зависимости от текущей папки и локального профиля автора.
- Версии runtime и пакетов зафиксированы.
- Сетевой доступ указан как требование.
- Нет интерактивных prompts.
- UTF-8 и окончания строк проверены.
- Ошибки имеют ненулевые exit codes.
- Матрица CI совпадает с заявлением compatibility.
- Windows, macOS и Linux не перечислены без фактического запуска.