Claude Code Skills: пишем агентные промпты на основе исследований

Почему большинство агентных промптов не работают

Каждый, кто хоть раз пробовал автоматизировать задачу с помощью AI-агента, сталкивался с одной и той же проблемой: промпт, который блестяще работал в тестах, разваливается в продакшне. Агент путается, галлюцинирует, не соблюдает инструкции — и всё это после того, как вы потратили часы на «магическое заклинание» в системном промпте.

Большинство туториалов учат писать системные промпты как заклинания — найди правильную формулировку, и модель послушается. Это не так.

Реальность оказалась куда интереснее. Когда разработчики начали серьёзно изучать внутреннее устройство Claude Code и инструментов вроде DeepAgents, выяснилось: большинство того, что люди считают важным в системных промптах, на самом деле не имеет значения. А то, что действительно важно — почти никто не обсуждает.

В этой статье мы разберём, как создавать Claude Code Skills специально для написания агентных промптов — и как опираться при этом на реальные исследования, а не на интуицию.

Что такое Claude Code Skills и зачем они нужны

Прежде чем писать промпты для агентов, важно понять инструмент. Skills — это папки с инструкциями, скриптами и ресурсами, которые Claude обнаруживает и динамически загружает по мере необходимости. Думайте о них как о специализированных учебных пособиях: вы один раз описываете процесс — и Claude умеет его воспроизводить в любом контексте.

Claude Code Skill находится между ad hoc промптингом и Python-библиотекой. Баланс гибкости и ограничений делает его подходящим для упаковки AI-воркфлоу, которые повторяются, но не идентичны каждый раз.

ℹ Чем Skill отличается от slash-команды

Slash-команды (/competitive-research, /today) — это именованные промпты в markdown-файлах. Skills добавляют поверх этого три вещи: директорию для вспомогательных файлов, frontmatter для управления вызовом, и возможность автоматической загрузки когда контекст релевантен.

Skills добавляют опциональные возможности: директорию для поддерживающих файлов, frontmatter для управления тем, кто их вызывает — вы или Claude, — и способность Claude загружать их автоматически при необходимости.

Claude Code Skills следуют открытому стандарту Agent Skills, который работает в нескольких AI-инструментах. Claude Code расширяет стандарт дополнительными возможностями: управлением вызовом, запуском субагентов и динамической инъекцией контекста.

Структура типичного SKILL.md

---
name: write-agent-prompt
description: Writes a research-grounded agent prompt for a given task
context: fork
agent: Explore
---

Write an agent prompt for $ARGUMENTS.

Follow these research-backed principles:
1. Define clear success criteria
2. Specify tool permissions explicitly
3. Add reversibility checks for destructive actions
4. Use progressive disclosure for knowledge

Когда вы или Claude вызываете Skill, отрендеренный контент SKILL.md входит в разговор как единое сообщение и остаётся там до конца сессии. Claude Code не перечитывает файл Skill на последующих ходах, поэтому пишите руководство, которое должно применяться на протяжении всей задачи, как постоянные инструкции, а не одноразовые шаги.

Архитектура агентного промпта: что говорит исследование

Изучение реальных системных промптов Claude Code — в частности, работа сообщества по реверс-инжинирингу его внутренней архитектуры — дала несколько неочевидных инсайтов.

Прогрессивное раскрытие вместо знаниевых свалок

Ключевой принцип — прогрессивное раскрытие, а не «свалка знаний». Вместо того чтобы вставлять все 200 API-эндпоинтов в системный промпт, дайте модели инструмент для их поиска. Эту стратегию разделяют система Skills в Claude Code и Progressive Disclosure middleware в DeepAgents — оба загружают знания по требованию через вызовы инструментов, а не предзагружают всё.


graph TD
    A[Агентный промпт] --> B{Нужны знания?}
    B -->|Нет| C[Выполнить задачу]
    B -->|Да| D[Вызов инструмента]
    D --> E[Загрузить документацию / Skill]
    E --> C
    C --> F[Результат]
    F --> G{Деструктивное действие?}
    G -->|Нет| H[Выполнить]
    G -->|Да| I[Подтверждение пользователя]
    I --> H

Управление контекстом и «деградация контекста»

Одна из главных проблем долгих агентных сессий — то, что исследователи называют context rot (деградация контекста). По мере роста диалога приверженность модели инструкциям системного промпта деградирует (заметно при 80K+ токенах). Инъекция напоминаний в середину разговора освежает правила через эффект недавности.

Если вы используете Claude в агентной обвязке, которая сжимает контекст или позволяет сохранять его во внешние файлы (как в Claude Code), добавьте эту информацию в промпт — иначе Claude иногда будет пытаться завершить работу по мере приближения к лимиту контекста.

Безопасность и обратимость действий

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

⚠ Деструктивные операции

Обязательно перечисляйте в промпте действия, требующие подтверждения: rm -rf, git push --force, git reset --hard, удаление таблиц БД, отправка сообщений в публичные каналы. Без явного списка агент будет интерпретировать это по-своему.

Skill для написания агентных промптов: пошаговое построение

Теперь соберём всё вместе и создадим Skill, который будет помогать Claude писать другие агентные промпты — с опорой на исследования.

Шаг 1. Определите структуру директории

.claude/
  skills/
    write-agent-prompt/
      SKILL.md          # главный файл Skill
      research.md       # база знаний по промпт-инжинирингу
      templates/
        base-agent.md
        research-agent.md
        code-agent.md

Skills всегда сохраняются в файле SKILL.md. Папка, в которой они сохранены, определяет имя Skill. Поскольку Skills могут включать скрипты, они именуются директорией. Сам Skill определён в файле SKILL.md внутри этой директории. Связанные скрипты и контекст тоже могут находиться в ней.

Шаг 2. Напишите frontmatter

---
name: write-agent-prompt
description: >-
  Creates a research-backed agent system prompt.
  Use when asked to build, write, or design an agent prompt.
context: fork
agent: Explore
allowed-tools: Read, Glob, Grep
---

Шаг 3. Опишите задачу с критериями успеха

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

## Задача
Напиши агентный системный промпт для: $ARGUMENTS

## Критерии успеха
- Промпт содержит явные инструкции по инструментам
- Определены обратимые и необратимые действия
- Использована структура progressive disclosure
- Добавлена логика обработки контекстного окна
- Промпт протестирован на типовых сценариях

## Шаги
1. Прочти research.md для принципов
2. Выбери подходящий шаблон из templates/
3. Адаптируй под задачу $ARGUMENTS
4. Проверь на соответствие критериям выше

Шаг 4. Наполните research.md реальными исследованиями

Файл research.md — это то, что отличает Skill «на основе исследований» от обычного. Он должен содержать задокументированные принципы:

# Принципы агентного промпт-инжиниринга

## Качество описания инструментов
Качество определения инструментов напрямую влияет на
эффективность агента. Инвестируйте время в отличные
описания инструментов.

## Кэширование промптов
Размещайте статичный контент первым, динамичный — последним.
Структура: системный промпт → определения инструментов →
CLAUDE.md → история диалога.

## Борьба с context rot
При 80K+ токенов инжектируйте напоминания об основных правилах.

Практические паттерны из реальных кейсов

Специализация агентов вместо универсальных промптов

Один промпт Claude, пытающийся одновременно проверять грамматику, разметку, математику и код, будет делать всё это посредственно. Специализированные агенты фокусируются на одном измерении и делают это тщательно.

Подход «один агент — одна задача» — один из самых мощных паттернов. Вот как он реализуется через Skill:

---
name: slide-excellence
description: Parallel quality review of presentation slides
context: fork
agent: Task
---

Review $ARGUMENTS using parallel specialized agents:
- grammar-agent: syntax and spelling
- layout-agent: visual structure
- math-agent: formulas and calculations
- code-agent: code blocks

Spawn all agents simultaneously, then synthesize results.

Не все агенты нуждаются в одной и той же модели. Каждый файл агента имеет поле model: в YAML frontmatter. По умолчанию все агенты используют model: inherit (ту модель, которую использует ваша основная сессия).

Паттерн «прогрессивного раскрытия» в Skills

Skills используют прогрессивное раскрытие, чтобы Claude оставался эффективным. При работе над задачами Claude сначала сканирует метаданные Skill (описания и сводки), чтобы найти подходящие. Если Skill подходит, Claude загружает полные инструкции. Наконец, если Skill включает исполняемый код или справочные файлы, они загружаются только по необходимости. Эта архитектура означает, что вы можете иметь много Skills без перегрузки контекстного окна Claude. Claude получает доступ именно к тому, что нужно, когда это нужно.

Динамический контекст через shell-команды

Одна из мощнейших возможностей Skills — инъекция реальных данных прямо в промпт:

Синтаксис !\<команда>`` запускает shell-команды до того, как контент Skill отправляется Claude. Вывод команды заменяет плейсхолдер, так что Claude получает реальные данные, а не саму команду.

---
name: prompt-audit
description: Audit existing agent prompts in the codebase
context: fork
agent: Explore
allowed-tools: Bash(find *), Read
---

## Контекст проекта
- Текущие промпты: !`find .claude -name "*.md" | head -20`
- Структура: !`ls -la .claude/skills/`
- Git статус: !`git status --short`

## Задача
Проверь все найденные промпты на соответствие принципам
исследовательского prompt engineering.

💡 Совет по использованию $ARGUMENTS

$ARGUMENTS — это специальная переменная, которая принимает всё, что написано после имени Skill при вызове. Например, /write-agent-prompt code reviewer for Python передаст строку «code reviewer for Python» как аргумент. Используйте её, чтобы сделать Skill универсальным.

Сравнение подходов к написанию агентных промптов

Подход	Гибкость	Надёжность	Переиспользование	Лучше всего для
Ad hoc промпт	Высокая	Низкая	Нет	Эксперименты, одноразовые задачи
Slash-команда	Средняя	Средняя	Частично	Повторяющиеся задачи одного типа
Claude Code Skill	Высокая	Высокая	Да	Сложные воркфлоу с вариациями
Субагент с кастомным промптом	Низкая	Очень высокая	Нет	Специализированные изолированные задачи
Python-библиотека	Низкая	Очень высокая	Да	Полностью детерминированные задачи

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

Оптимизация кэширования: экономим до 90% стоимости

Если вы используете агентные Skills в продакшне через API, вопрос стоимости становится критичным. Для агентов это особенно важно: вы повторно отправляете системный промпт + определения инструментов при каждом отдельном вызове LLM внутри разговора.

Вот исследованная структура, которая максимизирует кэш-хиты:

✅ Cache-friendly порядок в SKILL.md:
1. Системные инструкции (статичные)     ← Cache breakpoint 1
2. Определения инструментов (статичные) ← Cache breakpoint 2  
3. CLAUDE.md / правила проекта          ← Cache breakpoint 3
4. История диалога                      ← Breakpoint 4

❌ Cache-разрушающий порядок:
1. Системные инструкции
2. ДИНАМИЧЕСКАЯ МЕТКА ВРЕМЕНИ ← всё после неё = промах кэша
3. Определения инструментов

📝 Реальный пример

При правильном кэшировании стоимость повторного запроса снижается до 10% от обычной цены (90% экономии). Первая запись в кэш стоит 125% от обычной цены, но окупается уже со второго запроса. Размещайте динамические данные (пользовательский ввод, временные метки) всегда в конце промпта.

Заключение: от магических заклинаний к инженерии

Context engineering стал всё более важной частью работы с LLM, а prompt engineering — его ключевым строительным блоком. Prompt engineering — это мастерство структурирования инструкций для получения лучших результатов от AI-моделей. Это то, как вы формулируете запросы, задаёте стиль, предоставляете контекст и направляете поведение модели для достижения ваших целей.

Claude Code Skills — это следующий эволюционный шаг: не просто «лучший промпт», а инженерная система для работы с AI-агентами. Ключевые принципы, которые мы разобрали:

Прогрессивное раскрытие — загружай знания по требованию, не перегружай контекст
Специализация — один агент, одна задача, максимальное качество
Явное управление обратимостью — разграничивай безопасные и деструктивные действия
Борьба с context rot — инжектируй напоминания в длинных сессиях
Кэширование — статичный контент первым, динамичный последним

Prompt engineering — это не разовая задача, а творческий экспериментальный процесс. Чем больше вы итерируете свои промпты, тем больше будете раскрывать тонкие закономерности, превращающие хороший промпт в отличный.

Создайте свой первый исследовательский Skill сегодня — начните с малого: write-agent-prompt для своей предметной области. Опирайтесь на задокументированные принципы, тестируйте на реальных сценариях, и вы обнаружите, что разрыв между «агент иногда работает» и «агент работает надёжно» — это почти всегда вопрос правильно спроектированного промпта.