| 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 и т.д.):
- Создай подпапку
scripts/ рядом с SKILL.md
- Вынеси скрипт в
scripts/<имя>.sh (или .py, .ts)
- В SKILL.md оставь только ссылку:
## audit-gitignore.sh
Скрипт: `scripts/audit-gitignore.sh`
Проверяет:
- Какие файлы игнорируются
- Скан на секреты
- Рекомендации
- В SKILL.md НЕ вставляй
<details> с кодом скрипта
- Сделай скрипт исполняемым:
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/ | Промпты для разных сценариев |
При создании нового скилла
mkdir -p .agents/skills/<name>/scripts- SKILL.md — только правила и описание
- Скрипты — в
scripts/
- Сделай
chmod +x scripts/*.sh
