Shell-скрипты для облачной песочницы Claude

Правила проекта polyakov-claude-skills

plugin.json — формат манифеста

При создании/редактировании .claude-plugin/plugin.json:

• author — ОБЯЗАТЕЛЬНО объект: {"name": "Polyakov"}. Строка вызывает ошибку валидации.
• skills — НЕ валидное поле. Не добавлять. Скиллы обнаруживаются автоматически из skills/ директории.
• Эталонный формат:

  {
    "name": "plugin-name",
    "version": "1.0.0",
    "description": "...",
    "author": {
      "name": "Polyakov"
    }
  }
  

marketplace.json

• При добавлении нового плагина — обязательно добавить запись в .claude-plugin/marketplace.json → plugins[], иначе плагин не будет виден через /plugin install.

Shell-скрипты для облачной песочницы Claude

Скрипты скиллов исполняются в облачной песочнице Claude (cloud sandbox). Она имеет ограничения, которые ломают стандартные bash-подходы. Ниже — правила, выведенные из практики.

Шелл и совместимость

• Шебанг: #!/bin/sh, не #!/bin/bash. В песочнице bash может отсутствовать.
• Никаких башизмов: [[ ]] → [ ], ${BASH_SOURCE[0]} → $0, source → ., local → переменные с префиксом _funcname_.
• Никаких внешних source common.sh — всё инлайнить в скрипт. Песочница может не разрешить чтение соседних файлов.
• Эталон: plugins/fal-ai-image/skills/fal-ai-image/scripts/ (commit 6410d65).

Stdout буфер — главная ловушка

• Песочница имеет ограничение на размер stdout (~4–64 KB, точное значение — issue #48).
• Если скрипт выводит больше лимита — молчаливый отказ: "Error running command", без вывода и без stderr.
• Симптом: маленькие скрипты (quota.sh, ~200 байт вывода) работают, большие (top_requests.sh с JSON ~50 KB) — нет.

Решение: temp file вместо переменной

# ПЛОХО — ответ API в переменной, echo | grep ломается на большом JSON
result=$(curl -s ...)
echo "$result" | grep ...

# ХОРОШО — ответ в файл, grep читает файл напрямую
TMPFILE="${TMPDIR:-/tmp}/result_$$.json"
trap 'rm -f "$TMPFILE"' EXIT
curl -s ... | tr -d '\n\r' > "$TMPFILE"
grep ... "$TMPFILE"

• tr -d '\n\r' нормализует JSON в одну строку для безопасного парсинга через grep/sed.
• trap cleanup EXIT гарантирует удаление файла.
• Переменная $$ (PID) делает имя файла уникальным.

Чеклист при создании нового скрипта

1. #!/bin/sh + set -e
2. Инлайн конфиг: [ -f "$CONFIG" ] && . "$CONFIG"
3. API-ответ → temp file, не переменная
4. Всё чтение данных — grep/sed по файлу, не echo "$var" | ...
5. Минимум stdout: таблицы ≤20 строк, остальное в CSV/файл
6. Никаких local, [[ ]], source, массивов bash