Урок 11 из 16•15 мин
Best Practices организации навыков
Цели урока
После прохождения этого урока вы сможете:
- 1Изучить лучшие практики структурирования навыков
- 2Понять принципы версионирования
- 3Научиться документировать навыки
Структура хорошего навыка
За время работы с навыками сообщество выработало best practices, которые помогают создавать maintainable и эффективные навыки.
1. Чёткое описание триггеров
Плохо
## Description
Этот навык помогает с аналитикой.
Этот навык помогает с аналитикой.
Хорошо
## Description
Активируй этот навык, когда пользователь:
- Просит проанализировать маркетинговые данные
- Упоминает ROAS, CPA, CTR, конверсии
- Хочет отчёт по рекламным кампаниям
- Работает с данными Яндекс.Директ, VK Ads, Google Ads
Активируй этот навык, когда пользователь:
- Просит проанализировать маркетинговые данные
- Упоминает ROAS, CPA, CTR, конверсии
- Хочет отчёт по рекламным кампаниям
- Работает с данными Яндекс.Директ, VK Ads, Google Ads
2. Модульность файлов
Разделяйте логику на отдельные файлы вместо одного огромного SKILL.md:
| Файл | Содержимое |
|---|---|
| SKILL.md | Общая логика, точка входа |
| rules/ | Бизнес-правила |
| templates/ | Шаблоны выходных документов |
| scripts/ | Код для вычислений |
| examples/ | Примеры входов и выходов |
3. Версионирование
Добавляйте версию в навык для отслеживания изменений:
markdown
# Marketing Analyst
**Version:** 2.1.0
**Last Updated:** 2026-01-15
**Changelog:**
- 2.1.0: Добавлена поддержка Telegram Ads
- 2.0.0: Переход на MCP для получения данных
- 1.0.0: Начальная версия
## Description
...4. Graceful Degradation
Навык должен работать даже если часть зависимостей недоступна:
markdown
### Получение данных
Приоритет:
1. MCP postgres → живые данные
2. Файл CSV → если MCP недоступен
3. Ручной ввод → последний resort
При недоступности источника объясни пользователю альтернативы.5. Примеры использования
Добавляйте примеры диалогов в папку examples/:
markdown
# examples/basic_analysis.md
## Пример: Базовый анализ кампании
**Пользователь:**
Проанализируй данные рекламной кампании за прошлую неделю
**Агент:**
[Загружает marketing-analyst skill]
[Запрашивает источник данных]
Для анализа мне нужны данные. Выберите способ:
1. Подключиться к БД (если настроен MCP)
2. Загрузить CSV файл
**Пользователь:**
[Загружает campaign_week5.csv]
**Агент:**
[Выполняет анализ по правилам из SKILL.md]
[Генерирует отчёт]
📊 Анализ завершён. Вот ключевые findings:
...Правило
Хорошо документированный навык — это навык, который можно передать коллеге без дополнительных объяснений.
Храните навыки в Git. Это даёт историю изменений, возможность rollback и совместной работы.
Вопросы для размышления
- •Какие навыки в вашей работе требуют версионирования?
- •Как вы организуете документацию для своих навыков?