Лучшие практики создания 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): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Пример 2:**
Вход: Исправлена ошибка, где даты отображались неправильно в отчётах
Вывод:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

**Пример 3:**
Вход: Обновлены зависимости и переработана обработка ошибок
Вывод:
```
chore: update dependencies and refactor error handling

- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```

Следуйте этому стилю: 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": "Extract all text from this PDF file and save it to output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
    "Extracts text content from all pages in the document without missing any pages",
    "Saves the extracted text to a file named output.txt in a clear, readable format"
  ]
}

Разрабатывайте 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 обрабатывайте условия ошибок, а не перекладывайте на Claude.

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

def process_file(path):
    """Process a file, creating it if it doesn't exist."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Create file with default content instead of failing
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Provide alternative instead of failing
        print(f"Cannot access {path}, using default")
        return ""

Плохой пример: Перекладывайте на Claude:

def process_file(path):
    # Just fail and let Claude figure it out
    return open(path).read()

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

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

# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3

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

TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 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
# Returns: "OK" or lists conflicts
```

**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 исправить проблемы.

Зависимости пакетов

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

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

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

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

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

Как это влияет на вашу разработку:

Как Claude получает доступ к навыкам:

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

• Пути к файлам имеют значение: Claude навигирует по каталогу вашего навыка как по файловой системе. Используйте прямые слэши (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 может навигировать и выборочно загружать ровно то, что требуется для каждой задачи.

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

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

Если ваш навык использует инструменты 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-тегов

Полные детали структуры см. в обзоре навыков.

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

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

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

Перед тем как поделиться навыком, проверьте:

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

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

Код и скрипты

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

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

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

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