Структура навыка: SKILL.md и файлы

Анатомия навыка

Каждый навык — это папка с определённой структурой. Минимальный навык состоит из одного файла, но реальные навыки обычно включают несколько файлов для разных целей.

plaintext

marketing-analyst/
├── SKILL.md              # Обязательный: точка входа
├── budget_rules.md       # Правила перераспределения бюджета
├── report_template.md    # Шаблон отчёта
├── scripts/
│   └── calculate_roas.py # Python скрипт для расчётов
└── examples/
    └── sample_report.xlsx # Пример итогового отчёта

SKILL.md — сердце навыка

Файл SKILL.md — единственный обязательный файл в навыке. Он содержит три ключевых элемента:

Имя навыка — короткое название, по которому агент идентифицирует навык
Описание — когда активировать этот навык (триггеры)
Инструкции — что делать, когда навык активирован

Вот пример SKILL.md для навыка маркетингового аналитика:

markdown

# Marketing Analyst

## Description
Активируй этот навык, когда пользователь просит:
- Проанализировать маркетинговые данные или кампании
- Создать отчёт по эффективности рекламы
- Перераспределить рекламный бюджет
- Работать с данными Яндекс.Директ, VK Ads, Telegram Ads

## Instructions

### Анализ данных
1. Запроси CSV файл с данными кампании
2. Проверь наличие обязательных колонок: channel, impressions, clicks, cost, conversions, revenue
3. Рассчитай ключевые метрики для каждого канала:
   - CTR = clicks / impressions
   - CPC = cost / clicks
   - CPA = cost / conversions
   - ROAS = revenue / cost

### Перераспределение бюджета
Используй правила из @budget_rules.md

### Формат отчёта
Используй шаблон из @report_template.md

### Создание Excel
Создай файл с 4 листами:
1. Executive Summary — ключевые метрики
2. Funnel Analysis — воронка по каналам
3. Efficiency Analysis — CPA и ROAS
4. Raw Data — исходные данные с расчётами

Символ @

Символ @ в инструкциях указывает на другой файл в папке навыка. Когда агент видит @budget_rules.md, он знает, что нужно загрузить и прочитать этот файл.

Прогрессивное раскрытие контекста

Ключевая особенность навыков — прогрессивное раскрытие. Не все файлы загружаются сразу. Это экономит токены и ускоряет работу.

Что загружается	Когда	Зачем
Имя + Описание	Всегда в контексте	Чтобы агент знал о существовании навыка
Инструкции (SKILL.md)	При активации навыка	Основные правила работы
Дополнительные файлы (@)	По необходимости	Детальные правила, шаблоны, примеры

Например, если пользователь просит только «посчитать ROAS», агенту не нужно загружать шаблон отчёта. Он загрузит только те файлы, которые реально нужны для текущей задачи.

Дополнительные файлы навыка

Кроме SKILL.md, навык может включать:

Тип файла	Назначение	Пример
Markdown (.md)	Правила, инструкции, шаблоны	budget_rules.md, report_template.md
Python (.py)	Скрипты для вычислений	calculate_metrics.py
JSON (.json)	Конфигурации, данные	thresholds.json
Примеры	Образцы результатов	sample_output.xlsx

Требования к агенту

Чтобы использовать навыки, агент должен иметь базовый набор инструментов:

Доступ к файловой системе — читать и записывать файлы
Bash/Shell — выполнять команды и скрипты
Опционально: MCP серверы — для доступа к внешним данным

Claude Code

Claude Code уже имеет все необходимые инструменты для работы с навыками. Просто положите папку навыка в ~/.claude/skills/ или в папку .claude/skills/ вашего проекта.

Пример: файл budget_rules.md

markdown

# Правила перераспределения бюджета

## Увеличение бюджета (+10-20%)
Канал получает больше бюджета, если:
- ROAS > 3.0 (каждый рубль приносит 3+ рубля)
- CPA < 300₽ (стоимость конверсии ниже нормы)
- CTR > 2% (высокая кликабельность)

## Уменьшение бюджета (-10-20%)
Канал теряет бюджет, если:
- ROAS < 1.5 (низкая окупаемость)
- CPA > 500₽ (дорогие конверсии)
- CTR < 0.5% (низкая кликабельность)

## Стоп-лист
Полностью остановить канал, если:
- ROAS < 1.0 (убыточный)
- 0 конверсий за неделю
- CPA > 1000₽

## Ограничения
- Не менять бюджет более чем на 20% за раз
- Минимальный бюджет канала: 5000₽/день
- Всегда оставлять тестовый бюджет для новых каналов

Чем более структурированы ваши дополнительные файлы, тем лучше агент понимает правила. Используйте заголовки, списки, конкретные числа и условия.

Когда агент загружает дополнительные файлы навыка (например, @budget_rules.md)?

Анатомия навыка

plaintext

marketing-analyst/
├── SKILL.md              # Обязательный: точка входа
├── budget_rules.md       # Правила перераспределения бюджета
├── report_template.md    # Шаблон отчёта
├── scripts/
│   └── calculate_roas.py # Python скрипт для расчётов
└── examples/
    └── sample_report.xlsx # Пример итогового отчёта

SKILL.md — сердце навыка

Файл SKILL.md — единственный обязательный файл в навыке. Он содержит три ключевых элемента:

Имя навыка — короткое название, по которому агент идентифицирует навык
Описание — когда активировать этот навык (триггеры)
Инструкции — что делать, когда навык активирован

Вот пример SKILL.md для навыка маркетингового аналитика:

markdown

# Marketing Analyst

## Description
Активируй этот навык, когда пользователь просит:
- Проанализировать маркетинговые данные или кампании
- Создать отчёт по эффективности рекламы
- Перераспределить рекламный бюджет
- Работать с данными Яндекс.Директ, VK Ads, Telegram Ads

## Instructions

### Анализ данных
1. Запроси CSV файл с данными кампании
2. Проверь наличие обязательных колонок: channel, impressions, clicks, cost, conversions, revenue
3. Рассчитай ключевые метрики для каждого канала:
   - CTR = clicks / impressions
   - CPC = cost / clicks
   - CPA = cost / conversions
   - ROAS = revenue / cost

### Перераспределение бюджета
Используй правила из @budget_rules.md

### Формат отчёта
Используй шаблон из @report_template.md

### Создание Excel
Создай файл с 4 листами:
1. Executive Summary — ключевые метрики
2. Funnel Analysis — воронка по каналам
3. Efficiency Analysis — CPA и ROAS
4. Raw Data — исходные данные с расчётами

Символ @

Прогрессивное раскрытие контекста

Что загружается	Когда	Зачем
Имя + Описание	Всегда в контексте	Чтобы агент знал о существовании навыка
Инструкции (SKILL.md)	При активации навыка	Основные правила работы
Дополнительные файлы (@)	По необходимости	Детальные правила, шаблоны, примеры

Дополнительные файлы навыка

Кроме SKILL.md, навык может включать:

Тип файла	Назначение	Пример
Markdown (.md)	Правила, инструкции, шаблоны	budget_rules.md, report_template.md
Python (.py)	Скрипты для вычислений	calculate_metrics.py
JSON (.json)	Конфигурации, данные	thresholds.json
Примеры	Образцы результатов	sample_output.xlsx

Требования к агенту

Чтобы использовать навыки, агент должен иметь базовый набор инструментов:

Доступ к файловой системе — читать и записывать файлы
Bash/Shell — выполнять команды и скрипты
Опционально: MCP серверы — для доступа к внешним данным

Claude Code

Пример: файл budget_rules.md

markdown

# Правила перераспределения бюджета

## Увеличение бюджета (+10-20%)
Канал получает больше бюджета, если:
- ROAS > 3.0 (каждый рубль приносит 3+ рубля)
- CPA < 300₽ (стоимость конверсии ниже нормы)
- CTR > 2% (высокая кликабельность)

## Уменьшение бюджета (-10-20%)
Канал теряет бюджет, если:
- ROAS < 1.5 (низкая окупаемость)
- CPA > 500₽ (дорогие конверсии)
- CTR < 0.5% (низкая кликабельность)

## Стоп-лист
Полностью остановить канал, если:
- ROAS < 1.0 (убыточный)
- 0 конверсий за неделю
- CPA > 1000₽

## Ограничения
- Не менять бюджет более чем на 20% за раз
- Минимальный бюджет канала: 5000₽/день
- Всегда оставлять тестовый бюджет для новых каналов

Когда агент загружает дополнительные файлы навыка (например, @budget_rules.md)?

Цели урока

Анатомия навыка

SKILL.md — сердце навыка

Прогрессивное раскрытие контекста

Дополнительные файлы навыка

Требования к агенту

Пример: файл budget_rules.md

Вопросы для размышления

Структура навыка: SKILL.md и файлы

Цели урока

Анатомия навыка

SKILL.md — сердце навыка

Прогрессивное раскрытие контекста

Дополнительные файлы навыка

Требования к агенту

Пример: файл budget_rules.md

Вопросы для размышления