Лучшие практики создания Skills

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

Для концептуального понимания того, как работают Skills, см. обзор Skills.

Основные принципы

Лаконичность — ключ к успеху

Контекстное окно — это общественное благо. Ваш Skill делит контекстное окно со всем остальным, что нужно знать Claude, включая:

• Системный промпт
• Историю разговора
• Метаданные других Skills
• Ваш фактический запрос

Не каждый токен в вашем Skill имеет непосредственную стоимость. При запуске загружаются только метаданные (имя и описание) всех Skills. Claude читает SKILL.md только когда Skill становится релевантным, и читает дополнительные файлы только по мере необходимости. Однако лаконичность в SKILL.md по-прежнему важна: как только Claude загружает его, каждый токен конкурирует с историей разговора и другим контекстом.

Предположение по умолчанию: Claude уже очень умный

Добавляйте только контекст, который Claude еще не имеет. Проверьте каждую информацию:

• "Действительно ли Claude нужно это объяснение?"
• "Могу ли я предположить, что Claude это знает?"
• "Оправдывает ли этот абзац свою стоимость в токенах?"

Хороший пример: Лаконичный (примерно 50 токенов):

## Извлечение текста из PDF

Используйте pdfplumber для извлечения текста:

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Плохой пример: Слишком многословный (примерно 150 токенов):

## Извлечение текста из PDF

PDF (Portable Document Format) — это распространенный формат файлов, который содержит
текст, изображения и другое содержимое. Для извлечения текста из PDF вам потребуется
использовать библиотеку. Доступно много библиотек для обработки PDF, но мы
рекомендуем pdfplumber, потому что она легко использовать и она хорошо справляется с большинством случаев.
Сначала вам нужно установить ее с помощью pip. Затем вы можете использовать код ниже...

Лаконичная версия предполагает, что Claude знает, что такое PDF и как работают библиотеки.

Установите надлежащие степени свободы

Соответствуйте уровню специфичности хрупкости и вариативности задачи.

Высокая свобода (текстовые инструкции):

Используйте когда:

• Несколько подходов действительны
• Решения зависят от контекста
• Эвристики направляют подход

Пример:

## Процесс проверки кода

1. Анализируйте структуру и организацию кода
2. Проверьте на потенциальные ошибки или граничные случаи
3. Предложите улучшения для читаемости и поддерживаемости
4. Проверьте соответствие соглашениям проекта

Средняя свобода (псевдокод или скрипты с параметрами):

Используйте когда:

• Существует предпочтительный паттерн
• Некоторая вариация приемлема
• Конфигурация влияет на поведение

Пример:

## Создание отчета

Используйте этот шаблон и настройте по мере необходимости:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Обработка данных
    # Создание вывода в указанном формате
    # Опционально включение визуализаций
```

Низкая свобода (специфические скрипты, мало или нет параметров):

Используйте когда:

• Операции хрупкие и подвержены ошибкам
• Консистентность критична
• Должна быть соблюдена конкретная последовательность

Пример:

## Миграция базы данных

Запустите ровно этот скрипт:

```bash
python scripts/migrate.py --verify --backup
```

Не изменяйте команду и не добавляйте дополнительные флаги.

Аналогия: Думайте о Claude как о роботе, исследующем путь:

• Узкий мост с пропастями по обе стороны: Есть только один безопасный путь вперед. Предоставьте специфические ограждения и точные инструкции (низкая свобода). Пример: миграции баз данных, которые должны выполняться в точной последовательности.
• Открытое поле без опасностей: Много путей ведут к успеху. Дайте общее направление и доверьте Claude найти лучший маршрут (высокая свобода). Пример: проверка кода, где контекст определяет лучший подход.

Тестируйте со всеми моделями, которые вы планируете использовать

Skills действуют как дополнения к моделям, поэтому эффективность зависит от базовой модели. Тестируйте ваш Skill со всеми моделями, которые вы планируете использовать.

Рекомендации по тестированию по моделям:

• Claude Haiku (быстрый, экономичный): Предоставляет ли Skill достаточно руководства?
• Claude Sonnet (сбалансированный): Ясен ли Skill и эффективен?
• Claude Opus (мощное рассуждение): Избегает ли Skill чрезмерного объяснения?

То, что идеально работает для Opus, может потребовать больше деталей для Haiku. Если вы планируете использовать ваш Skill с несколькими моделями, стремитесь к инструкциям, которые хорошо работают со всеми из них.

Структура Skill

Соглашения об именовании

Используйте последовательные паттерны именования, чтобы облегчить ссылки на Skills и обсуждение. Мы рекомендуем использовать форму герундия (глагол + -ing) для имен Skills, так как это четко описывает деятельность или возможность, которую предоставляет Skill.

Помните, что поле name должно использовать только строчные буквы, цифры и дефисы.

Хорошие примеры имен (форма герундия):

• processing-pdfs
• analyzing-spreadsheets
• managing-databases
• testing-code
• writing-documentation

Приемлемые альтернативы:

• Именные фразы: pdf-processing, spreadsheet-analysis
• Ориентированные на действие: process-pdfs, analyze-spreadsheets

Избегайте:

• Неясные имена: helper, utils, tools
• Слишком общие: documents, data, files
• Зарезервированные слова: anthropic-helper, claude-tools
• Несогласованные паттерны в вашей коллекции skills

Согласованное именование облегчает:

• Ссылки на Skills в документации и разговорах
• Понимание того, что делает Skill с первого взгляда
• Организацию и поиск через несколько Skills
• Поддержание профессиональной, согласованной библиотеки skills

Написание эффективных описаний

Поле description позволяет обнаружить Skill и должно включать как то, что делает Skill, так и когда его использовать.

Будьте конкретны и включайте ключевые термины. Включайте как то, что делает Skill, так и конкретные триггеры/контексты для того, когда его использовать.

Каждый Skill имеет ровно одно поле описания. Описание критично для выбора skill: Claude использует его для выбора правильного Skill из потенциально 100+ доступных Skills. Ваше описание должно предоставить достаточно деталей для Claude, чтобы знать, когда выбрать этот Skill, в то время как остальная часть SKILL.md предоставляет детали реализации.

Эффективные примеры:

Skill обработки PDF:

description: Извлекает текст и таблицы из файлов PDF, заполняет формы, объединяет документы. Используйте при работе с файлами PDF или когда пользователь упоминает PDF, формы или извлечение документов.

Skill анализа Excel:

description: Анализирует электронные таблицы Excel, создает сводные таблицы, создает диаграммы. Используйте при анализе файлов Excel, электронных таблиц, табличных данных или файлов .xlsx.

Skill помощника Git Commit:

description: Создает описательные сообщения коммитов путем анализа git diffs. Используйте когда пользователь просит помощь в написании сообщений коммитов или просмотре поставленных изменений.

Избегайте неясных описаний, таких как эти:

description: Помогает с документами

description: Обрабатывает данные

description: Делает что-то с файлами

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

SKILL.md служит обзором, который указывает Claude на подробные материалы по мере необходимости, как оглавление в руководстве по адаптации. Для объяснения того, как работает прогрессивное раскрытие, см. Как работают Skills в обзоре.

Практическое руководство:

• Держите тело SKILL.md под 500 строк для оптимальной производительности
• Разделите содержимое на отдельные файлы при приближении к этому пределу
• Используйте паттерны ниже для эффективной организации инструкций, кода и ресурсов

Визуальный обзор: От простого к сложному

Базовый Skill начинается с просто файла SKILL.md, содержащего метаданные и инструкции:

По мере роста вашего Skill вы можете объединить дополнительное содержимое, которое Claude загружает только при необходимости:

Полная структура каталога Skill может выглядеть так:

pdf/
├── SKILL.md              # Основные инструкции (загружаются при срабатывании)
├── FORMS.md              # Руководство по заполнению форм (загружается по мере необходимости)
├── reference.md          # Справка API (загружается по мере необходимости)
├── examples.md           # Примеры использования (загружаются по мере необходимости)
└── scripts/
    ├── analyze_form.py   # Служебный скрипт (выполняется, не загружается)
    ├── fill_form.py      # Скрипт заполнения форм
    └── validate.py       # Скрипт валидации

Паттерн 1: Высокоуровневое руководство со ссылками

---
name: pdf-processing
description: Извлекает текст и таблицы из файлов PDF, заполняет формы и объединяет документы. Используйте при работе с файлами PDF или когда пользователь упоминает PDF, формы или извлечение документов.
---

# Обработка PDF

## Быстрый старт

Извлеките текст с помощью pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Продвинутые функции

**Заполнение форм**: См. [FORMS.md](FORMS.md) для полного руководства
**Справка API**: См. [REFERENCE.md](REFERENCE.md) для всех методов
**Примеры**: См. [EXAMPLES.md](EXAMPLES.md) для распространенных паттернов

Claude загружает FORMS.md, REFERENCE.md или EXAMPLES.md только при необходимости.

Паттерн 2: Организация по доменам

Для Skills с несколькими доменами организуйте содержимое по доменам, чтобы избежать загрузки нерелевантного контекста. Когда пользователь спрашивает о метриках продаж, Claude нужно прочитать только схемы, связанные с продажами, а не данные финансов или маркетинга. Это держит использование токенов низким и контекст сосредоточенным.

bigquery-skill/
├── SKILL.md (обзор и навигация)
└── reference/
    ├── finance.md (доход, метрики выставления счетов)
    ├── sales.md (возможности, конвейер)
    ├── product.md (использование API, функции)
    └── marketing.md (кампании, атрибуция)

# Анализ данных BigQuery

## Доступные наборы данных

**Финансы**: Доход, ARR, выставление счетов → См. [reference/finance.md](reference/finance.md)
**Продажи**: Возможности, конвейер, учетные записи → См. [reference/sales.md](reference/sales.md)
**Продукт**: Использование API, функции, внедрение → См. [reference/product.md](reference/product.md)
**Маркетинг**: Кампании, атрибуция, электронная почта → См. [reference/marketing.md](reference/marketing.md)

## Быстрый поиск

Найдите конкретные метрики с помощью grep:

```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```

Паттерн 3: Условные детали

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

# Обработка DOCX

## Создание документов

Используйте docx-js для новых документов. См. [DOCX-JS.md](DOCX-JS.md).

## Редактирование документов

Для простых правок измените XML напрямую.

**Для отслеживаемых изменений**: См. [REDLINING.md](REDLINING.md)
**Для деталей OOXML**: См. [OOXML.md](OOXML.md)

Claude читает REDLINING.md или OOXML.md только когда пользователю нужны эти функции.

Избегайте глубоко вложенных ссылок

Claude может частично читать файлы, когда они ссылаются из других ссылаемых файлов. При встрече с вложенными ссылками Claude может использовать команды, такие как head -100, для предварительного просмотра содержимого, а не чтения полных файлов, что приводит к неполной информации.

Держите ссылки на один уровень глубины от SKILL.md. Все справочные файлы должны ссылаться непосредственно из SKILL.md, чтобы гарантировать, что Claude читает полные файлы при необходимости.

Плохой пример: Слишком глубоко:

# SKILL.md
См. [advanced.md](advanced.md)...

# advanced.md
См. [details.md](details.md)...

# details.md
Вот фактическая информация...

Хороший пример: Один уровень глубины:

# SKILL.md

**Базовое использование**: [инструкции в SKILL.md]
**Продвинутые функции**: См. [advanced.md](advanced.md)
**Справка API**: См. [reference.md](reference.md)
**Примеры**: См. [examples.md](examples.md)

Структурируйте более длинные справочные файлы с оглавлением

Для справочных файлов длиннее 100 строк включите оглавление в верхней части. Это гарантирует, что Claude может видеть полный объем доступной информации даже при предварительном просмотре с частичными чтениями.

Пример:

# Справка API

## Содержание
- Аутентификация и настройка
- Основные методы (создание, чтение, обновление, удаление)
- Продвинутые функции (пакетные операции, вебхуки)
- Паттерны обработки ошибок
- Примеры кода

## Аутентификация и настройка
...

## Основные методы
...

Claude может затем прочитать полный файл или перейти к конкретным разделам по мере необходимости.

Для деталей того, как эта архитектура на основе файловой системы позволяет прогрессивное раскрытие, см. раздел Среда выполнения в разделе Advanced ниже.

Рабочие процессы и циклы обратной связи

Используйте рабочие процессы для сложных задач

Разбейте сложные операции на четкие, последовательные шаги. Для особенно сложных рабочих процессов предоставьте контрольный список, который Claude может скопировать в свой ответ и отметить по мере прогресса.

Пример 1: Рабочий процесс синтеза исследований (для Skills без кода):

## Рабочий процесс синтеза исследований

Скопируйте этот контрольный список и отслеживайте ваш прогресс:

```
Прогресс исследования:
- [ ] Шаг 1: Прочитайте все исходные документы
- [ ] Шаг 2: Определите ключевые темы
- [ ] Шаг 3: Перекрестно ссылайтесь на утверждения
- [ ] Шаг 4: Создайте структурированное резюме
- [ ] Шаг 5: Проверьте цитаты
```

**Шаг 1: Прочитайте все исходные документы**

Просмотрите каждый документ в каталоге `sources/`. Отметьте основные аргументы и подтверждающие доказательства.

**Шаг 2: Определите ключевые темы**

Ищите паттерны в источниках. Какие темы повторяются? Где источники согласны или не согласны?

**Шаг 3: Перекрестно ссылайтесь на утверждения**

Для каждого основного утверждения проверьте, что оно появляется в исходном материале. Отметьте, какой источник поддерживает каждый пункт.

**Шаг 4: Создайте структурированное резюме**

Организуйте результаты по темам. Включите:
- Основное утверждение
- Подтверждающие доказательства из источников
- Противоречивые точки зрения (если есть)

**Шаг 5: Проверьте цитаты**

Проверьте, что каждое утверждение ссылается на правильный исходный документ. Если цитаты неполные, вернитесь к шагу 3.

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

Пример 2: Рабочий процесс заполнения форм PDF (для Skills с кодом):

## Рабочий процесс заполнения форм PDF

Скопируйте этот контрольный список и отмечайте элементы по мере их завершения:

```
Прогресс задачи:
- [ ] Шаг 1: Анализируйте форму (запустите analyze_form.py)
- [ ] Шаг 2: Создайте сопоставление полей (отредактируйте fields.json)
- [ ] Шаг 3: Проверьте сопоставление (запустите validate_fields.py)
- [ ] Шаг 4: Заполните форму (запустите fill_form.py)
- [ ] Шаг 5: Проверьте вывод (запустите verify_output.py)
```

**Шаг 1: Анализируйте форму**

Запустите: `python scripts/analyze_form.py input.pdf`

Это извлекает поля формы и их местоположения, сохраняя в `fields.json`.

**Шаг 2: Создайте сопоставление полей**

Отредактируйте `fields.json`, чтобы добавить значения для каждого поля.

**Шаг 3: Проверьте сопоставление**

Запустите: `python scripts/validate_fields.py fields.json`

Исправьте любые ошибки валидации перед продолжением.

**Шаг 4: Заполните форму**

Запустите: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Шаг 5: Проверьте вывод**

Запустите: `python scripts/verify_output.py output.pdf`

Если проверка не пройдена, вернитесь к шагу 2.

Четкие шаги предотвращают пропуск Claude критической валидации. Контрольный список помогает как Claude, так и вам отслеживать прогресс через многошаговые рабочие процессы.

Реализуйте циклы обратной связи

Распространенный паттерн: Запустите валидатор → исправьте ошибки → повторите

Этот паттерн значительно улучшает качество вывода.

Пример 1: Соответствие руководству стиля (для Skills без кода):

## Процесс проверки содержимого

1. Создайте ваше содержимое, следуя руководствам в STYLE_GUIDE.md
2. Проверьте против контрольного списка:
   - Проверьте консистентность терминологии
   - Проверьте, что примеры следуют стандартному формату
   - Подтвердите, что все требуемые разделы присутствуют
3. Если найдены проблемы:
   - Отметьте каждую проблему с конкретной ссылкой на раздел
   - Пересмотрите содержимое
   - Проверьте контрольный список снова
4. Продолжайте только когда все требования выполнены
5. Завершите и сохраните документ

Это показывает паттерн цикла валидации, используя справочные документы вместо скриптов. "Валидатор" — это STYLE_GUIDE.md, и Claude выполняет проверку путем чтения и сравнения.

Пример 2: Процесс редактирования документа (для Skills с кодом):

## Процесс редактирования документа

1. Внесите ваши правки в `word/document.xml`
2. **Проверьте немедленно**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Если валидация не пройдена:
   - Внимательно прочитайте сообщение об ошибке
   - Исправьте проблемы в XML
   - Запустите валидацию снова
4. **Продолжайте только когда валидация пройдена**
5. Пересоберите: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Протестируйте выходной документ

Цикл валидации ловит ошибки рано.

Рекомендации по содержимому

Избегайте информации, чувствительной ко времени

Не включайте информацию, которая устареет:

Плохой пример: Чувствительный ко времени (станет неправильным):

Если вы делаете это до августа 2025, используйте старый API.
После августа 2025 используйте новый API.

Хороший пример (используйте раздел "старые паттерны"):

## Текущий метод

Используйте конечную точку API v2: `api.example.com/v2/messages`

## Старые паттерны

<details>
<summary>Устаревший API v1 (устарел 2025-08)</summary>

API v1 использовал: `api.example.com/v1/messages`

Эта конечная точка больше не поддерживается.
</details>

Раздел старых паттернов предоставляет исторический контекст без загромождения основного содержимого.

Используйте согласованную терминологию

Выберите один термин и используйте его на протяжении всего Skill:

Хорошо - Согласованно:

• Всегда "конечная точка API"
• Всегда "поле"
• Всегда "извлечение"

Плохо - Несогласованно:

• Смешивайте "конечная точка API", "URL", "маршрут API", "путь"
• Смешивайте "поле", "коробка", "элемент", "управление"
• Смешивайте "извлечение", "вытягивание", "получение", "получение"

Согласованность помогает Claude понять и следовать инструкциям.

Распространенные паттерны

Паттерн шаблона

Предоставьте шаблоны для формата вывода. Соответствуйте уровню строгости вашим потребностям.

Для строгих требований (как ответы API или форматы данных):

## Структура отчета

ВСЕГДА используйте эту точную структуру шаблона:

```markdown
# [Название анализа]

## Резюме руководителя
[Однопараграфный обзор ключевых результатов]

## Ключевые результаты
- Результат 1 с поддерживающими данными
- Результат 2 с поддерживающими данными
- Результат 3 с поддерживающими данными

## Рекомендации
1. Конкретная действенная рекомендация
2. Конкретная действенная рекомендация
```

Для гибкого руководства (когда адаптация полезна):

## Структура отчета

Вот разумный формат по умолчанию, но используйте ваше лучшее суждение на основе анализа:

```markdown
# [Название анализа]

## Резюме руководителя
[Обзор]

## Ключевые результаты
[Адаптируйте разделы на основе того, что вы обнаружите]

## Рекомендации
[Адаптируйте к конкретному контексту]
```

Адаптируйте разделы по мере необходимости для конкретного типа анализа.

Паттерн примеров

Для Skills, где качество вывода зависит от просмотра примеров, предоставьте пары ввода/вывода, как в обычном промптировании:

## Формат сообщения коммита

Создавайте сообщения коммитов, следуя этим примерам:

**Пример 1:**
Ввод: Добавлена аутентификация пользователя с токенами JWT
Вывод:
```
feat(auth): реализуйте аутентификацию на основе JWT

Добавьте конечную точку входа и промежуточное ПО валидации токена
```

**Пример 2:**
Ввод: Исправлена ошибка, когда даты отображались неправильно в отчетах
Вывод:
```
fix(reports): исправьте форматирование даты в преобразовании часовых поясов

Используйте временные метки UTC последовательно при создании отчетов
```

**Пример 3:**
Ввод: Обновлены зависимости и переработана обработка ошибок
Вывод:
```
chore: обновите зависимости и переработайте обработку ошибок

- Обновите lodash до 4.17.21
- Стандартизируйте формат ответа об ошибке на всех конечных точках
```

Следуйте этому стилю: type(scope): краткое описание, затем подробное объяснение.

Примеры помогают Claude понять желаемый стиль и уровень деталей более четко, чем описания одни.

Паттерн условного рабочего процесса

Направляйте Claude через точки решения:

## Рабочий процесс модификации документа

1. Определите тип модификации:

   **Создание нового содержимого?** → Следуйте "Рабочему процессу создания" ниже
   **Редактирование существующего содержимого?** → Следуйте "Рабочему процессу редактирования" ниже

2. Рабочий процесс создания:
   - Используйте библиотеку docx-js
   - Создайте документ с нуля
   - Экспортируйте в формат .docx

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

Оценка и итерация

Создайте оценки в первую очередь

Создайте оценки ДО написания обширной документации. Это гарантирует, что ваш Skill решает реальные проблемы, а не документирует воображаемые.

Разработка, управляемая оценками:

1. Определите пробелы: Запустите Claude на репрезентативных задачах без Skill. Документируйте конкретные сбои или отсутствующий контекст
2. Создайте оценки: Создайте три сценария, которые тестируют эти пробелы
3. Установите базовый уровень: Измерьте производительность Claude без Skill
4. Напишите минимальные инструкции: Создайте ровно столько содержимого, чтобы заполнить пробелы и пройти оценки
5. Итерируйте: Выполните оценки, сравните с базовым уровнем и уточните

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

Структура оценки:

{
  "skills": ["pdf-processing"],
  "query": "Извлеките весь текст из этого файла PDF и сохраните его в output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Успешно читает файл PDF, используя подходящую библиотеку обработки PDF или инструмент командной строки",
    "Извлекает текстовое содержимое со всех страниц в документе без пропуска каких-либо страниц",
    "Сохраняет извлеченный текст в файл с именем output.txt в четком, читаемом формате"
  ]
}

Разрабатывайте Skills итеративно с Claude

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

Создание нового Skill:

1. Завершите задачу без Skill: Работайте над проблемой с Claude A, используя обычное промптирование. По мере работы вы естественно предоставите контекст, объясните предпочтения и поделитесь процедурными знаниями. Обратите внимание на то, какую информацию вы повторно предоставляете.

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

   Пример: Если вы работали над анализом BigQuery, вы могли предоставить имена таблиц, определения полей, правила фильтрации (такие как "всегда исключайте тестовые учетные записи") и распространенные паттерны запросов.

3. Попросите Claude A создать Skill: "Создайте Skill, который захватывает этот паттерн анализа BigQuery, который мы только что использовали. Включите схемы таблиц, соглашения об именовании и правило об исключении тестовых учетных записей."

   Модели Claude понимают формат и структуру Skill нативно. Вам не нужны специальные системные промпты или "writing skills" skill, чтобы заставить Claude помочь создать Skills. Просто попросите Claude создать Skill, и он создаст правильно структурированное содержимое SKILL.md с соответствующим frontmatter и телом.

4. Проверьте на лаконичность: Проверьте, что Claude A не добавил ненужные объяснения. Спросите: "Удалите объяснение о том, что означает процент побед — Claude это уже знает."

5. Улучшите информационную архитектуру: Попросите Claude A организовать содержимое более эффективно. Например: "Организуйте это так, чтобы схема таблицы была в отдельном справочном файле. Мы можем добавить больше таблиц позже."

6. Тестируйте на похожих задачах: Используйте Skill с Claude B (свежий экземпляр с загруженным Skill) на связанных случаях использования. Наблюдайте, находит ли Claude B правильную информацию, применяет ли правила правильно и успешно ли справляется с задачей.

7. Итерируйте на основе наблюдения: Если Claude B борется или что-то пропускает, вернитесь к Claude A с конкретикой: "Когда Claude использовал этот Skill, он забыл отфильтровать по дате для Q4. Должны ли мы добавить раздел о паттернах фильтрации по датам?"

Итерирование существующих Skills:

Тот же иерархический паттерн продолжается при улучшении Skills. Вы чередуетесь между:

• Работой с Claude A (эксперт, который помогает уточнить Skill)
• Тестированием с Claude B (агент, использующий Skill для выполнения реальной работы)
• Наблюдением поведения Claude B и возвращением идей к Claude A

1. Используйте Skill в реальных рабочих процессах: Дайте Claude B (с загруженным Skill) фактические задачи, а не тестовые сценарии

2. Наблюдайте поведение Claude B: Отметьте, где он борется, преуспевает или делает неожиданный выбор

   Пример наблюдения: "Когда я попросил Claude B создать региональный отчет о продажах, он написал запрос, но забыл отфильтровать тестовые учетные записи, даже хотя Skill упоминает это правило."

3. Вернитесь к Claude A для улучшений: Поделитесь текущим SKILL.md и опишите, что вы наблюдали. Спросите: "Я заметил, что Claude B забыл отфильтровать тестовые учетные записи, когда я попросил региональный отчет. Skill упоминает фильтрацию, но может быть это недостаточно выделено?"

4. Проверьте предложения Claude A: Claude A может предложить переорганизацию, чтобы сделать правила более выделенными, использование более сильного языка, такого как "ДОЛЖЕН отфильтровать" вместо "всегда отфильтровать", или переструктурирование раздела рабочего процесса.

5. Примените и тестируйте изменения: Обновите Skill с уточнениями Claude A, затем тестируйте снова с Claude B на похожих запросах

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

Сбор отзывов команды:

1. Поделитесь Skills с товарищами по команде и наблюдайте их использование
2. Спросите: Активируется ли Skill при ожидании? Ясны ли инструкции? Что отсутствует?
3. Включите отзывы, чтобы решить слепые пятна в ваших собственных паттернах использования

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

Наблюдайте, как Claude навигирует Skills

По мере итерирования Skills обратите внимание на то, как Claude фактически их использует на практике. Следите за:

• Неожиданными путями исследования: Читает ли Claude файлы в порядке, который вы не предвидели? Это может указывать, что ваша структура не так интуитивна, как вы думали
• Пропущенными соединениями: Не следует ли Claude ссылкам на важные файлы? Ваши ссылки могут быть менее явными или выделенными
• Чрезмерной опорой на определенные разделы: Если Claude повторно читает один и тот же файл, рассмотрите, должно ли это содержимое быть в основном SKILL.md вместо этого
• Игнорируемым содержимым: Если Claude никогда не получает доступ к объединенному файлу, он может быть ненужным или плохо обозначенным в основных инструкциях

Итерируйте на основе этих наблюдений, а не предположений. 'name' и 'description' в метаданных вашего Skill особенно критичны. Claude использует их при решении, активировать ли Skill в ответ на текущую задачу. Убедитесь, что они четко описывают, что делает Skill и когда его следует использовать.

Антипаттерны, которых следует избегать

Избегайте путей в стиле Windows

Всегда используйте прямые слэши в путях файлов, даже на Windows:

• ✓ Хорошо: scripts/helper.py, reference/guide.md
• ✗ Избегайте: scripts\helper.py, reference\guide.md

Пути в стиле Unix работают на всех платформах, в то время как пути в стиле Windows вызывают ошибки на системах Unix.

Избегайте предложения слишком много вариантов

Не представляйте несколько подходов, если это не необходимо:

**Плохой пример: Слишком много выборов** (запутанно):
"Вы можете использовать pypdf, или pdfplumber, или PyMuPDF, или pdf2image, или..."

**Хороший пример: Предоставьте значение по умолчанию** (с выходом):
"Используйте pdfplumber для извлечения текста:
```python
import pdfplumber
```

Для отсканированных PDF, требующих OCR, используйте pdf2image с pytesseract вместо этого."

Advanced: Skills с исполняемым кодом

Разделы ниже сосредоточены на Skills, которые включают исполняемые скрипты. Если ваш Skill использует только инструкции markdown, перейдите к Контрольному списку для эффективных Skills.

Решайте, не избегайте

При написании скриптов для Skills обрабатывайте условия ошибок, а не избегайте их.

Хороший пример: Явно обрабатывайте ошибки:

def process_file(path):
    """Обработайте файл, создав его, если он не существует."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Создайте файл с содержимым по умолчанию вместо сбоя
        print(f"Файл {path} не найден, создание по умолчанию")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Предоставьте альтернативу вместо сбоя
        print(f"Не могу получить доступ к {path}, используя значение по умолчанию")
        return ''

Плохой пример: Избегайте к Claude:

def process_file(path):
    # Просто сбой и позвольте Claude разобраться
    return open(path).read()

Параметры конфигурации также должны быть обоснованы и задокументированы, чтобы избежать "магических констант" (закон Остерхаута). Если вы не знаете правильное значение, как Claude его определит?

Хороший пример: Самодокументирующийся:

# HTTP запросы обычно завершаются в течение 30 секунд
# Более длительный timeout учитывает медленные соединения
REQUEST_TIMEOUT = 30

# Три повтора балансируют надежность и скорость
# Большинство перемежающихся сбоев разрешаются ко второму повтору
MAX_RETRIES = 3

Плохой пример: Магические числа:

TIMEOUT = 47  # Почему 47?
RETRIES = 5   # Почему 5?

Предоставьте служебные скрипты

Даже если Claude мог бы написать скрипт, предварительно созданные скрипты предлагают преимущества:

Преимущества служебных скриптов:

• Более надежны, чем созданный код
• Экономят токены (нет необходимости включать код в контекст)
• Экономят время (не требуется создание кода)
• Обеспечивают консистентность при использовании

Диаграмма выше показывает, как исполняемые скрипты работают рядом с файлами инструкций. Файл инструкций (forms.md) ссылается на скрипт, и Claude может его выполнить без загрузки его содержимого в контекст.

Важное различие: Уточните в ваших инструкциях, должен ли Claude:

• Выполнить скрипт (наиболее распространено): "Запустите analyze_form.py для извлечения полей"
• Прочитать как справку (для сложной логики): "См. analyze_form.py для алгоритма извлечения полей"

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

Пример:

## Служебные скрипты

**analyze_form.py**: Извлеките все поля формы из PDF

```bash
python scripts/analyze_form.py input.pdf > fields.json
```

Формат вывода:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Проверьте на перекрывающиеся ограничивающие коробки

```bash
python scripts/validate_boxes.py fields.json
# Возвращает: "OK" или список конфликтов
```

**fill_form.py**: Примените значения полей к PDF

```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

Используйте визуальный анализ

Когда входные данные могут быть отрендерены как изображения, попросите Claude их анализировать:

## Анализ макета формы

1. Преобразуйте PDF в изображения:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Анализируйте каждое изображение страницы для определения полей формы
3. Claude может видеть местоположения и типы полей визуально

Возможности видения Claude помогают понять макеты и структуры.

Создайте проверяемые промежуточные выходы

Когда Claude выполняет сложные, открытые задачи, он может делать ошибки. Паттерн "план-валидация-выполнение" ловит ошибки рано, заставляя Claude сначала создать план в структурированном формате, затем валидировать этот план со скриптом перед выполнением.

Пример: Представьте, что вы просите Claude обновить 50 полей формы в PDF на основе электронной таблицы. Без валидации Claude может ссылаться на несуществующие поля, создавать конфликтующие значения, пропускать требуемые поля или неправильно применять обновления.

Решение: Используйте паттерн рабочего процесса, показанный выше (заполнение формы PDF), но добавьте промежуточный файл changes.json, который получает валидацию перед применением изменений. Рабочий процесс становится: анализ → создание файла плана → валидация плана → выполнение → проверка.

Почему этот паттерн работает:

• Ловит ошибки рано: Валидация находит проблемы перед применением изменений
• Машинно-проверяемо: Скрипты предоставляют объективную верификацию
• Обратимое планирование: Claude может итерировать план без касания оригиналов
• Четкая отладка: Сообщения об ошибках указывают на конкретные проблемы

Когда использовать: Пакетные операции, деструктивные изменения, сложные правила валидации, высокоставочные операции.

Совет реализации: Сделайте скрипты валидации многословными с конкретными сообщениями об ошибках, такими как "Поле 'signature_date' не найдено. Доступные поля: customer_name, order_total, signature_date_signed", чтобы помочь Claude исправить проблемы.

Упакуйте зависимости

Skills работают в среде выполнения кода с ограничениями, специфичными для платформы:

• claude.ai: Может устанавливать пакеты из npm и PyPI и вытягивать из репозиториев GitHub
• Anthropic API: Не имеет доступа в сеть и нет установки пакетов во время выполнения

Перечислите требуемые пакеты в вашем SKILL.md и проверьте, что они доступны в документации инструмента выполнения кода.

Среда выполнения

Skills работают в среде выполнения кода с доступом к файловой системе, командам bash и возможностями выполнения кода. Для концептуального объяснения этой архитектуры см. Архитектура Skills в обзоре.

Как это влияет на ваше создание:

Как Claude получает доступ к Skills:

1. Метаданные предварительно загружены: При запуске имя и описание из YAML frontmatter всех Skills загружаются в системный промпт
2. Файлы читаются по требованию: Claude использует инструменты bash Read для доступа к SKILL.md и другим файлам из файловой системы при необходимости
3. Скрипты выполняются эффективно: Служебные скрипты могут быть выполнены через bash без загрузки их полного содержимого в контекст. Только вывод скрипта потребляет токены
4. Нет штрафа контекста за большие файлы: Справочные файлы, данные или документация не потребляют токены контекста до фактического чтения

• Пути файлов имеют значение: Claude навигирует по вашему каталогу skill как по файловой системе. Используйте прямые слэши (reference/guide.md), а не обратные слэши
• Назовите файлы описательно: Используйте имена, которые указывают содержимое: form_validation_rules.md, а не doc2.md
• Организуйте для обнаружения: Структурируйте каталоги по домену или функции
  • Хорошо: reference/finance.md, reference/sales.md
  • Плохо: docs/file1.md, docs/file2.md
• Объедините комплексные ресурсы: Включите полную документацию API, обширные примеры, большие наборы данных; нет штрафа контекста до доступа
• Предпочитайте скрипты для детерминированных операций: Напишите validate_form.py вместо того, чтобы просить Claude создать код валидации
• Сделайте намерение выполнения четким:
  • "Запустите analyze_form.py для извлечения полей" (выполнить)
  • "См. analyze_form.py для алгоритма извлечения" (прочитать как справку)
• Тестируйте паттерны доступа к файлам: Проверьте, что Claude может навигировать по вашей структуре каталогов, тестируя с реальными запросами

Пример:

bigquery-skill/
├── SKILL.md (обзор, указывает на справочные файлы)
└── reference/
    ├── finance.md (метрики доходов)
    ├── sales.md (данные конвейера)
    └── product.md (аналитика использования)

Когда пользователь спрашивает о доходе, Claude читает SKILL.md, видит ссылку на reference/finance.md и вызывает bash для чтения только этого файла. Файлы sales.md и product.md остаются в файловой системе, потребляя нулевые токены контекста до необходимости. Эта модель на основе файловой системы — это то, что позволяет прогрессивное раскрытие. Claude может навигировать и выборочно загружать ровно то, что требует каждая задача.

Для полных деталей технической архитектуры см. Как работают Skills в обзоре Skills.

Ссылки на инструменты MCP

Если ваш Skill использует инструменты MCP (Model Context Protocol), всегда используйте полностью квалифицированные имена инструментов, чтобы избежать ошибок "инструмент не найден".

Формат: ServerName:tool_name

Пример:

Используйте инструмент BigQuery:bigquery_schema для получения схем таблиц.
Используйте инструмент GitHub:create_issue для создания проблем.

Где:

• BigQuery и GitHub — имена серверов MCP
• bigquery_schema и create_issue — имена инструментов в этих серверах

Без префикса сервера Claude может не найти инструмент, особенно когда доступно несколько серверов MCP.

Избегайте предположения, что инструменты установлены

Не предполагайте, что пакеты доступны:

**Плохой пример: Предполагает установку**:
"Используйте библиотеку pdf для обработки файла."

**Хороший пример: Явно о зависимостях**:
"Установите требуемый пакет: `pip install pypdf`

Затем используйте его:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

Технические заметки

Требования YAML frontmatter

Frontmatter SKILL.md требует полей name и description с конкретными правилами валидации:

• name: Максимум 64 символа, только строчные буквы/цифры/дефисы, без XML тегов, без зарезервированных слов
• description: Максимум 1024 символа, непустой, без XML тегов

См. обзор Skills для полных деталей структуры.

Бюджеты токенов

Держите тело SKILL.md под 500 строк для оптимальной производительности. Если ваше содержимое превышает это, разделите его на отдельные файлы, используя паттерны прогрессивного раскрытия, описанные ранее. Для архитектурных деталей см. обзор Skills.

Контрольный список для эффективных Skills

Перед совместным использованием Skill проверьте:

Основное качество

• Описание конкретно и включает ключевые термины
• Описание включает как то, что делает Skill, так и когда его использовать
• Тело SKILL.md под 500 строк
• Дополнительные детали в отдельных файлах (если необходимо)
• Нет информации, чувствительной ко времени (или в разделе "старые паттерны")
• Согласованная терминология на протяжении
• Примеры конкретные, а не абстрактные
• Ссылки на файлы на один уровень глубины
• Прогрессивное раскрытие используется надлежащим образом
• Рабочие процессы имеют четкие шаги

Код и скрипты

• Скрипты решают проблемы, а не избегают их к Claude
• Обработка ошибок явная и полезная
• Нет "магических констант" (все значения обоснованы)
• Требуемые пакеты перечислены в инструкциях и проверены как доступные
• Скрипты имеют четкую документацию
• Нет путей в стиле Windows (все прямые слэши)
• Шаги валидации/проверки для критических операций
• Циклы обратной связи включены для задач, критичных для качества

Тестирование

• Минимум три оценки созданы
• Тестировано с Haiku, Sonnet и Opus
• Тестировано с реальными сценариями использования
• Отзывы команды включены (если применимо)

Следующие шаги