082 Claude 32bf512b

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

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

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

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

```sh
# ПЛОХО — ответ 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