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

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

Концептуальные основы работы навыков описаны в обзоре навыков.

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

Лаконичность — это главное

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

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

Не каждый токен в вашем навыке имеет немедленную стоимость. При запуске предварительно загружаются только метаданные (name и description) всех навыков. Claude читает SKILL.md только тогда, когда навык становится релевантным, а дополнительные файлы — только по мере необходимости. Однако лаконичность в 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 найти лучший маршрут (высокая свобода). Пример: ревью кода, где лучший подход определяется контекстом.

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

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

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

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

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

Структура навыка

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

Используйте единообразные шаблоны именования, чтобы на навыки было проще ссылаться и их было проще обсуждать. Рассмотрите использование формы герундия (глагол + -ing) для имён навыков, поскольку она ясно описывает деятельность или возможность, которую предоставляет навык.

Помните, что поле 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
• Несогласованных шаблонов внутри вашей коллекции навыков

Единообразное именование упрощает:

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

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

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

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

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

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

Навык обработки 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.

Навык анализа Excel:

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

Навык-помощник для 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 к подробным материалам по мере необходимости, подобно оглавлению в руководстве по адаптации. Объяснение того, как работает постепенное раскрытие (progressive disclosure), см. в разделе Как работают навыки обзора.

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

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

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

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

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

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

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

Шаблон 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: организация по предметным областям

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

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

# 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: рабочий процесс синтеза исследований (для навыков без кода):

## 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-форм (для навыков с кодом):

## 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: соответствие руководству по стилю (для навыков без кода):

## 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: процесс редактирования документа (для навыков с кодом):

## 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>

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

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

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

Хорошо — единообразно:

• Всегда "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.

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

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

## 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

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

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

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

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

1. Выявите пробелы: запустите Claude на репрезентативных задачах без навыка. Задокументируйте конкретные сбои или недостающий контекст
2. Создайте оценки: постройте три сценария, проверяющие эти пробелы
3. Установите базовый уровень: измерьте производительность Claude без навыка
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"
  ]
}

Разрабатывайте навыки итеративно вместе с Claude

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

Создание нового навыка:

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

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

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

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

4. Проверьте на лаконичность: убедитесь, что Claude A не добавил ненужных объяснений. Попросите: «Убери объяснение того, что означает win rate, — Claude это уже знает».

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

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

7. Итерируйте на основе наблюдений: если Claude B испытывает трудности или что-то упускает, вернитесь к Claude A с конкретикой: «Когда Claude использовал этот навык, он забыл отфильтровать по дате для Q4. Стоит ли добавить раздел о шаблонах фильтрации по дате?»

Итерации над существующими навыками:

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

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

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

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

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

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

4. Рассмотрите предложения Claude A: Claude A может предложить реорганизацию, чтобы сделать правила заметнее, использование более сильных формулировок, например «MUST filter» вместо «always filter», или перестройку раздела рабочего процесса.

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

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

Сбор обратной связи от команды:

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

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

Наблюдайте, как Claude ориентируется в навыках

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

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

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

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

Избегайте путей в стиле 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."

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

Следующие разделы посвящены навыкам, включающим исполняемые скрипты. Если ваш навык использует только инструкции в формате markdown, перейдите к разделу Чек-лист эффективных навыков.

Решайте, а не перекладывайте

При написании скриптов для навыков обрабатывайте ошибочные ситуации, а не перекладывайте их на 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 мог бы написать скрипт, готовые скрипты дают преимущества:

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

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

Приведённая выше диаграмма показывает, как исполняемые скрипты работают вместе с файлами инструкций. Файл инструкций (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 исправлять проблемы.

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

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

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

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

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

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

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

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

1. Метаданные предварительно загружены: при запуске name и description из YAML frontmatter всех навыков загружаются в системную подсказку
2. Файлы читаются по запросу: Claude использует инструменты чтения bash для доступа к 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), всегда используйте полностью квалифицированные имена инструментов, чтобы избежать ошибок «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: максимум 1024 символа, непустое, без XML-тегов

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

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

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

Чек-лист эффективных навыков

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

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

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

Код и скрипты

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

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

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

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