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

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

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



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



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

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

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

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

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

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

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

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

## Extract PDF text

Use pdfplumber for text extraction:

```python
import pdfplumber

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

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

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

Лаконичная версия предполагает, что у Claude уже есть информация о PDF и о том, как работают библиотеки.



Установите подходящую степень свободы

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

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

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

• Допустимы несколько подходов
• Решения зависят от контекста
• Подход определяется эвристиками

Пример:

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

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

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

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

Пример:

## Generate report

Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```

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

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

• Операции хрупкие и подвержены ошибкам
• Согласованность критически важна
• Необходимо следовать определённой последовательности

Пример:

## Database migration

Run exactly this script:

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

Do not modify the command or add additional flags.

Аналогия: Представьте 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 имеет ровно одно поле description. Описание критически важно для выбора skill: Claude использует его для выбора правильного Skill из потенциально более 100 доступных Skills. Ваше описание должно предоставлять достаточно деталей, чтобы Claude знал, когда выбрать этот Skill, в то время как остальная часть SKILL.md предоставляет детали реализации.

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

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

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Skill анализа Excel:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Skill помощника по Git-коммитам:

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Избегайте расплывчатых описаний, подобных этим:

description: Helps with documents

description: Processes data

description: Does stuff with files



Шаблоны прогрессивного раскрытия

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

Практические рекомендации:

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



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

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

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

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

pdf/
├── SKILL.md              # Main instructions (loaded when triggered)
├── FORMS.md              # Form-filling guide (loaded as needed)
├── reference.md          # API reference (loaded as needed)
├── examples.md           # Usage examples (loaded as needed)
└── scripts/
    ├── analyze_form.py   # Utility script (executed, not loaded)
    ├── fill_form.py      # Form filling script
    └── validate.py       # Validation script



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

---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

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

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

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



Шаблон 2: Организация по предметным областям

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

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)

## Quick search

Find specific metrics using grep:

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



Шаблон 3: Условные детали

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

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

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



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

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

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

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

# SKILL.md
See [advanced.md](advanced.md)...

# advanced.md
See [details.md](details.md)...

# details.md
Here's the actual information...

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

# SKILL.md

**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)



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

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

Пример:

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

## Core methods
...

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

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



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



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

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

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

## Research synthesis workflow

Copy this checklist and track your progress:

```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

**Step 1: Read all source documents**

Review each document in the `sources/` directory. Note the main arguments and supporting evidence.

**Step 2: Identify key themes**

Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?

**Step 3: Cross-reference claims**

For each major claim, verify it appears in the source material. Note which source supports each point.

**Step 4: Create structured summary**

Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)

**Step 5: Verify citations**

Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

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

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

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```

**Step 1: Analyze the form**

Run: `python scripts/analyze_form.py input.pdf`

This extracts form fields and their locations, saving to `fields.json`.

**Step 2: Create field mapping**

Edit `fields.json` to add values for each field.

**Step 3: Validate mapping**

Run: `python scripts/validate_fields.py fields.json`

Fix any validation errors before continuing.

**Step 4: Fill the form**

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

**Step 5: Verify output**

Run: `python scripts/verify_output.py output.pdf`

If verification fails, return to Step 2.

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



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

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

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

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

## Content review process

1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
   - Check terminology consistency
   - Verify examples follow the standard format
   - Confirm all required sections are present
3. If issues found:
   - Note each issue with specific section reference
   - Revise the content
   - Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document

Это показывает шаблон цикла валидации с использованием справочных документов вместо скриптов. «Валидатором» является STYLE_GUIDE.md, и Claude выполняет проверку путём чтения и сравнения.

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

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
   - Review the error message carefully
   - Fix the issues in the XML
   - Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document

Цикл валидации выявляет ошибки на раннем этапе.



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



Избегайте информации, зависящей от времени

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

Плохой пример: Зависит от времени (станет неверным):

If you're doing this before August 2025, use the old API.
After August 2025, use the new API.

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

## Current method

Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns

<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>

The v1 API used: `api.example.com/v1/messages`

This endpoint is no longer supported.
</details>

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



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

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

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

• Всегда «API endpoint»
• Всегда «field»
• Всегда «extract»

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

• Смешивание «API endpoint», «URL», «API route», «path»
• Смешивание «field», «box», «element», «control»
• Смешивание «extract», «pull», «get», «retrieve»

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



Распространённые шаблоны



Шаблон с заготовками

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

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

## Report structure

ALWAYS use this exact template structure:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

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

## Report structure

Here is a sensible default format, but use your best judgment based on the analysis:

```markdown
# [Analysis Title]

## Executive summary
[Overview]

## Key findings
[Adapt sections based on what you discover]

## Recommendations
[Tailor to the specific context]
```

Adjust sections as needed for the specific analysis type.



Шаблон с примерами

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

## Commit message format

Generate commit messages following these examples:

**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling

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

Follow this style: type(scope): brief description, then detailed explanation.

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



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

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

## Document modification workflow

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow" below
   **Editing existing content?** → Follow "Editing workflow" below

2. Creation workflow:
   - Use docx-js library
   - Build document from scratch
   - Export to .docx format

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
   - Repack when complete



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



Сначала создавайте оценки

Создавайте оценки ДО написания обширной документации. Это гарантирует, что ваш 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, который мы только что использовали. Включи схемы таблиц, соглашения об именовании и правило о фильтрации тестовых аккаунтов.»

4. Проверьте на лаконичность: Убедитесь, что Claude A не добавил ненужных объяснений. Попросите: «Удали объяснение того, что означает win rate — 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.



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

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

**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."



Продвинутое: 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:
        # Создать файл с содержимым по умолчанию вместо возврата ошибки
        print(f"File {path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""
    except PermissionError:
        # Предложить альтернативу вместо возврата ошибки
        print(f"Cannot access {path}, using default")
        return ""

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

def process_file(path):
    # Просто возвращаем ошибку и позволяем Claude разобраться самостоятельно
    return open(path).read()

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

Хороший пример: Самодокументируемый:

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

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

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

TIMEOUT = 47  # Why 47?
RETRIES = 5  # Why 5?



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

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

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

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

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

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

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

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

Пример:

## Utility scripts

**analyze_form.py**: Extract all form fields from PDF

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

Output format:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Check for overlapping bounding boxes

```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```

**fill_form.py**: Apply field values to PDF

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



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

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

## Form layout analysis

1. Convert PDF to images:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually

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



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

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

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

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

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

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

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

Совет по реализации: Делайте скрипты валидации подробными с конкретными сообщениями об ошибках, такими как «Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed», чтобы помочь Claude исправить проблемы.



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

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

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

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



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

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

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

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

1. Метаданные предварительно загружены: При запуске имя и описание из YAML frontmatter всех Skills загружаются в системную подсказку
2. Файлы читаются по требованию: Claude использует инструменты чтения bash для доступа к 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 (overview, points to reference files)
└── reference/
    ├── finance.md (revenue metrics)
    ├── sales.md (pipeline data)
    └── product.md (usage analytics)

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

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



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

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

Формат: ServerName:tool_name

Пример:

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Где:

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

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



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

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

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"



Технические примечания



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

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

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

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



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

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



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

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



Базовое качество

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



Код и скрипты

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



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

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



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