---
name: skill-file-structure
description: "Паттерн организации файлов скилла: SKILL.md + подпапки для скриптов/ресурсов. Никогда не держать инлайн-код в SKILL.md — выносить в scripts/."
triggers:
  - "структура скилла"
  - "как организовать скилл"
  - "файлы скилла"
  - "skill structure"
  - "куда положить скрипт"
---

# Структура файлов скилла

## Правило: SKILL.md не содержит инлайн-скриптов

**НИКОГДА** не размещай длинные скрипты, шаблоны или код прямо в SKILL.md.

### Правильная структура

```
.agents/skills/<skill-name>/
├── SKILL.md          # Описание, правила, триггеры
├── scripts/          # Исполняемые скрипты
│   ├── audit.sh
│   └── setup.sh
├── templates/        # Шаблоны файлов
│   └── .env.example
└── README.md         # Документация (опционально)
```

### Почему

| Проблема инлайн-кода в SKILL.md | Решение с подпапками |
|--------------------------------|---------------------|
| SKILL.md раздувается до 300+ строк | SKILL.md компактный, только правила |
| Скрипт нельзя запустить напрямую | `scripts/foo.sh` — исполняемый файл |
| Сложно обновлять скрипт отдельно | Скрипт живёт в своём файле |
| YAML фронтматтер ломается от спецсимволов в коде | Чистый YAML, код в отдельных файлах |

## Паттерн: вынос скрипта из SKILL.md

Если в SKILL.md есть секция с длинным скриптом (bash, python, ts и т.д.):

1. Создай подпапку `scripts/` рядом с SKILL.md
2. Вынеси скрипт в `scripts/<имя>.sh` (или .py, .ts)
3. В SKILL.md оставь только ссылку:

```markdown
## audit-gitignore.sh

Скрипт: `scripts/audit-gitignore.sh`

Проверяет:
- Какие файлы игнорируются
- Скан на секреты
- Рекомендации
```

4. В SKILL.md **НЕ** вставляй `<details>` с кодом скрипта
5. Сделай скрипт исполняемым: `chmod +x scripts/*.sh`

## Пример из практики

**До (плохо):** SKILL.md = 364 строки, 120 из них — bash-скрипт в блоке кода.

**После (хорошо):** SKILL.md = 247 строк, `scripts/audit-gitignore.sh` = 110 строк отдельно.

## Другие подпапки

| Подпапка | Назначение |
|----------|-----------|
| `scripts/` | Исполняемые скрипты (bash, python, node) |
| `templates/` | Шаблоны для копирования (.env.example, LICENSE и т.д.) |
| `assets/` | Ресурсы: изображения, иконки |
| `examples/` | Примеры использования |
| `prompts/` | Промпты для разных сценариев |

## При создании нового скилла

1. `mkdir -p .agents/skills/<name>/scripts`
2. SKILL.md — только правила и описание
3. Скрипты — в `scripts/`
4. Сделай `chmod +x scripts/*.sh`