Инструкция: Извлечь CLI из тела скила

Trigger: инструкция в школе содержит исходник CLI-утилиты в виде кодблока (например scripts/renderlayout.py, scripts/formsubmits.py), но в среде агента её нет на диске. Нужно положить и сделать исполняемой.

Зачем

Скилы часто включают тестированный CLI как inline-источник. Если каждый агент будет дёргать сырое API curl'ом — будет: ручная аутентификация, ручной парсинг ответа, разные баги. CLI инкапсулирует это один раз. Извлечение из тела скила — не «по желанию», а стандарт: меньше степеней свободы → меньше регрессий.

Шаги

1. Проверь не установлен ли уже

which <cli-name> 2>/dev/null

Если есть — проверь версию (если скрипт поддерживает --version) или git hash в шапке. Совпадает с тем что в школьной инструкции — пропусти шаги 2–4, иди к шагу 5.

2. Найди исходник в теле скила

В скиле должен быть кодблок:

```python
#!/usr/bin/env python3
"""
<имя> — <короткое описание>
"""
...
```

или для shell — соответствующий bash/sh блок.

Если в инструкции есть упоминание имени файла, но нет кодблока с исходником — стоп, эскалируй: «инструкция X ссылается на CLI Y, но не содержит исходник». Не пытайся восстановить по описанию.

3. Выбери путь установки

Доступно Путь Когда
/usr/local/bin/ системный агент с root в контейнере
~/bin/ или ~/.local/bin/ пользовательский без root, но в PATH
<vault>/scripts/ локальный fallback, если предыдущие закрыты

Проверь что выбранный путь в $PATH — иначе CLI потом не запустится без полного пути.

4. Запиши файл и сделай исполняемым

Через terminal:

cat > /usr/local/bin/<name> <<'PYEOF'
<здесь весь код из скила, дословно>
PYEOF
chmod +x /usr/local/bin/<name>

Важно: используй heredoc с одинарными кавычками 'PYEOF' — без переменных-подстановок. Иначе bash может попытаться расширить $variable внутри исходника.

5. Smoke-тест

<name> --help 2>&1 | head -5
  • Help выведен — отлично, иди дальше
  • Ошибка интерпретатора (python3: command not found, Permission denied) — фикси среду (установить python3, дать +x)
  • Help пустой/нерелевантный — версия из скила не совпадает с ожиданием, перечитай скил

6. Залогируй

В daily note:

HH:MM Установил CLI [[scripts/<name>]] по инструкции [[instructions/extract_cli_from_skill]].
Источник: [[instructions/<parent_skill>]]
Путь: /usr/local/bin/<name>

Создай scripts.md в vault (если нет) и добавь строку:

- [[<name>]] — из [[instructions/<parent_skill>]], установлен YYYY-MM-DD

Это аудит-журнал: позже понятно какие CLI стоят и откуда взялись.

7. Используй CLI, не сырое API

После установки прямой curl на API считается ошибкой. CLI протестирован, в нём предсказуемая обработка warnings/errors/auth. Если CLI чего-то не умеет — допиши CLI (обнови скил в школе), не обходи его.

Что НЕ делать

  • ❌ Не переписывай Python в свой стиль «как мне удобнее» — скил даёт работающую версию, твой ремейк может содержать баги
  • ❌ Не пропускай smoke-тест — лучше поймать python3 not found сразу, чем через минуту в реальном вызове
  • ❌ Не кладёшь CLI в /tmp/ — он там стёрётся между сессиями, придётся ставить заново
  • ❌ Не публикуй извлечённый CLI как новый файл в школе — он там уже есть, в теле родительской инструкции

Кейсы

Кейс 1: первый запуск check_layout_render
instructions/check_layout_render требует renderlayout.py. Агент: which renderlayout.py → нет → читает скил → находит кодблок → пишет в /usr/local/bin/renderlayout.py → chmod +x → --help → готово → возвращается к check_layout_render.

Кейс 2: вторая сессия — CLI уже стоит
Агент: which renderlayout.py → /usr/local/bin/renderlayout.py → smoke-тест проходит → пропускает извлечение → сразу использует.

Кейс 3: CLI не работает (python missing)
smoke-test падает с command not found. Агент: устанавливает Python через пакетный менеджер (apt/apk), повторяет smoke-тест. Если нет прав — эскалирует пользователю «нужен Python 3 в среде».

Связанные