Архитектура скиллов Claude: от простого к профессиональному

Почему архитектура скилла так важна

Простой скилл — это одна папка с одной инструкцией (SKILL.md-файл), где описаны три вещи:

• Что делает скилл
• Когда запускается
• Пошаговый план действий

На начальном этапе это работает. Но когда скилл растёт, всё находится в одном файле, логика смешана с ресурсами и правилами. Это усложняет модернизацию: каждое изменение требует поиска нужного места в большом текстовом файле, а вероятность сломать что-то возрастает.

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

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

Апгрейд 1: вынос ресурсов

Проблема: Источники (например, список сайтов) «зашиты» в инструкцию. Чтобы их изменить, нужно лезть в код скилла и вручную искать нужное место.

Решение: отдельный JSON файл

Решение: Вынести ресурсы в отдельный JSON файл — списки, данные, конфигурации, источники. Скилл читает этот файл в начале работы и использует данные из него.

Ключевой принцип: Progressive Disclosure

Progressive Disclosure (постепенное раскрытие): Скилль не держит всё в голове, а сначала читает файл с источниками, когда это нужно. Это экономит контекст и делает процесс прозрачнее.

Преимущества вынесения ресурсов

• Меняешь один JSON-файл — остальная архитектура не затрагивается
• Удобнее для редактирования (чистый структурированный формат вместо текста)
• Легче версионировать (git видит только изменения в данных, а не в логике)
• Другие скиллы могут переиспользовать те же ресурсы

Апгрейд 2: вынос логики (критический момент)

Проблема: Логика работы (например, обход сайтов и сбор информации) описана в инструкции текстом. Это создаёт две проблемы:

1. Непредсказуемость: Claude каждый раз может выполнить инструкцию чуть по-другому
2. Расход токенов: Модель думает о каждом шаге логики, когда можно просто запустить готовый скрипт

Решение: исполняемый скрипт на Python

Решение: Вынести исполняемую логику в отдельный скрипт (например, на Python). Главная инструкция скилла только запускает этот скрипт одной командой и анализирует результат.

Метод Метапромтинга (легко и без знания Python)

Не все умеют писать Python. Решение — метапромтинг (использовать Claude для создания промптов):

1. Попросить Claude: «Помоги мне составить промпт для генерации исполняемого файла внутри моего скилля. [Опиши задачу своими словами]»
2. Claude сгенерирует технически грамотный промпт с правильными терминами и структурой
3. Скопировать этот промпт в новый чат и выполнить. Claude создаст нужный Python-скрипт
4. Поместить скрипт в папку скилля и обновить главную инструкцию: «Запусти скрипт, проанализируй результат»

Результат

Результат: Главная инструкция лишь запускает скрипт одной командой. Скрипт возвращает готовые данные (например, JSON), а Claude тратит токены только на их анализ, а не на выполнение рутинных операций. Это экономит ~70% токенов и делает результат предсказуемым.

Совет: Это самый важный апгрейд. Переход логики в код удаляет главный источник непредсказуемости и расходов токенов.

Апгрейд 3: вынос правил

Проблема: Главная инструкция раздувается от триггеров, правил фильтрации, шаблонов оформления. Она становится энциклопедией вместо карты.

Решение: отдельные файлы с правилами

Решение: Вынести правила в отдельные файлы внутри папки скилля:

• Файл с правилами фильтрации (какие данные оставлять, какие отбрасывать)
• Файл-шаблон финального вида (как оформить результат)
• Файлы с правилами перевода, обработки дат, обработки ошибок и т.д.

Главная мысль: скилл — это карта, не энциклопедия

Главная мысль: Главный файл скилла должен быть картой, а не энциклопедией. Он только ссылается на другие файлы: «Прочитай правила из фильтры.txt, затем примени шаблон из шаблон.json».

⚠️ Критически важно: Когда вы пишете новый промпт для такого скилля, явно укажите: «Не дублируй эти правила в главной инструкции. Они должны жить только в своих файлах». Иначе Claude скопирует всё обратно «на всякий случай» из-за привычки быть полезным, и архитектура развалится.

Апгрейд 4: связь с внешним миром

Интеграция с внешними сервисами

Благодаря модульной архитектуре скилл легко интегрируется с внешними сервисами и другими скиллами. Вот примеры реализации:

• Notion: После формирования дайджеста скилл автоматически создаёт страницу в указанной базе Notion через коннектор (в SKILL.md просто добавляем команду вызова API Notion)
• Telegram: Скилл спрашивает пользователя, нужно ли сделать пост. Если «да», то вызывает другой, уже существующий скилл, который умеет писать посты в Telegram в определённом стиле

Итог: Простой скилл превращается в звено автоматизированного рабочего процесса. Он может взаимодействовать с другими инструментами и скиллами, расширяя возможности.

Четыре ключевых вывода

1. Собирайте скилл за один раз. Модернизация готового скилля — сложная задача. Лучше пересобрать его полностью по новому промпту с нуля, чем пытаться рефакторить старый
2. Используйте готовый шаблон. Если у вас есть скилль похожего назначения, возьмите его как основу. Подставьте свою задачу вместо переменных в готовый промпт
3. Апгрейды — опциональны. Не для всех задач нужны Python-скрипты или сложные правила. Ненужные апгрейды просто удалите из шаблона
4. Архитектура — это сила. Правильная модульная структура делает скиллы предсказуемыми, легко изменяемыми и готовыми к интеграции с внешними сервисами и другими скиллами

Важно: Архитектура — это не идеология, а инвестиция в будущее. Сейчас модульность кажется лишней работой, но когда нужно добавить третий источник или поменять формат вывода, вы пожалеете, что не сделали этого с самого начала.