---
title: Лучшие практики создания навыков
url: https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/best-practices
description: Узнайте, как писать эффективные навыки (Skills), которые Claude сможет обнаруживать и успешно использовать.
---

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

Концептуальное описание того, как работают Skills, см. в разделе [Agent Skills](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview).

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

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

[«Context window» (контекстное окно)](https://platform.claude.com/docs/ru/build-with-claude/context-windows) — это общий ресурс. Ваш Skill делит контекстное окно со всем остальным, что нужно Claude, включая:

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

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

**Исходное предположение:** Claude уже очень умён

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

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

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

````markdown
## 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 токенов):

```markdown
## 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 и о том, как работают библиотеки.

### Задавайте подходящую степень свободы

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

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

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

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

Пример:

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

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

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

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

Пример:

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

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

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

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

Пример:

````markdown
## 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. Если вы планируете использовать навык с несколькими моделями, стремитесь к инструкциям, которые хорошо работают со всеми из них.

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

<Note>
  **YAML Frontmatter:** frontmatter файла SKILL.md требует двух полей:

  `name`:

  * Максимум 64 символа
  * Должно содержать только строчные буквы, цифры и дефисы
  * Не может содержать XML-теги
  * Не может содержать зарезервированные слова: `anthropic`, `claude`

  `description`:

  * Должно быть непустым
  * Максимум 1024 символа
  * Не может содержать XML-теги
  * Должно описывать, что делает навык и когда его использовать

  Полное описание структуры Skill см. в разделе [Структура Skill](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#skill-structure) в Agent Skills.
</Note>

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

Используйте единообразные шаблоны именования, чтобы на навыки было проще ссылаться и их было проще обсуждать. Рассмотрите использование **формы герундия** (глагол + -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`
* Несогласованных шаблонов внутри вашей коллекции навыков

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

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

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

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

<Warning>
  **Всегда пишите в третьем лице**. Описание внедряется в системную подсказку, и несогласованная точка зрения может вызвать проблемы с обнаружением.

  * **Хорошо:** “Processes Excel files and generates reports”
  * **Избегайте:** “I can help you process Excel files”
  * **Избегайте:** “You can use this to process Excel files”
</Warning>

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

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

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

**Навык обработки PDF:**

```yaml
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:**

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

**Навык-помощник для Git-коммитов:**

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

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

```yaml
description: Helps with documents
```

```yaml
description: Processes data
```

```yaml
description: Does stuff with files
```

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

`SKILL.md` служит обзором, который направляет Claude к подробным материалам по мере необходимости, подобно оглавлению в руководстве для новых сотрудников. Объяснение того, как работает «progressive disclosure» (постепенное раскрытие), см. в разделе [Как работают Skills](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#how-skills-work) в обзоре.

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

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

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

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

<Frame>
  ![Простой файл SKILL.md, показывающий YAML frontmatter и тело в формате markdown](https://platform.claude.com/docs/ru/images/agent-skills-simple-file.svg)
</Frame>

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

<Frame>
  ![Добавление дополнительных справочных файлов, таких как reference.md и forms.md.](https://platform.claude.com/docs/ru/images/agent-skills-bundling-content.svg)
</Frame>

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

* `pdf/`

  * `SKILL.md`: основные инструкции (загружаются при срабатывании)

  * `FORMS.md`: руководство по заполнению форм (загружается по мере необходимости)

  * `reference.md`: справочник API (загружается по мере необходимости)

  * `examples.md`: примеры использования (загружаются по мере необходимости)

  * `scripts/`

    * `analyze_form.py`: вспомогательный скрипт (выполняется, не загружается)
    * `fill_form.py`: скрипт заполнения форм
    * `validate.py`: скрипт валидации

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

````markdown
---
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` (кампании, атрибуция)

````markdown SKILL.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: условные детали

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

```markdown
# 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 читал файлы полностью, когда это необходимо.

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

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

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

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

**Хороший пример: один уровень вложенности:**

```markdown
# 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 увидит полный объём доступной информации даже при предварительном просмотре с частичным чтением.

**Пример:**

```markdown
# 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 может прочитать файл целиком или перейти к конкретным разделам по мере необходимости.

Подробнее о том, как эта архитектура на основе файловой системы делает возможным постепенное раскрытие, см. в разделе [Среда выполнения](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/best-practices#runtime-environment) далее в этом руководстве.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```markdown
## 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 или форматы данных):

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

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

````markdown
## 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.
````

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

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

````markdown
## 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 через точки принятия решений:

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

<Tip>
  Если рабочие процессы становятся большими или сложными, с множеством шагов, рассмотрите возможность вынести их в отдельные файлы и указать Claude читать соответствующий файл в зависимости от текущей задачи.
</Tip>

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

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

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

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

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

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

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

```json
{
  "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"
  ]
}
```

<Note>
  Этот пример демонстрирует оценку на основе данных с простой рубрикой тестирования. В настоящее время нет встроенного способа запускать такие оценки. Вы можете создать собственную систему оценки. Оценки — ваш источник истины для измерения эффективности Skill.
</Note>

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

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

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

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

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

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

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

   <Tip>
     Модели Claude изначально понимают формат и структуру Skill. Вам не нужны специальные системные подсказки или Skill для «написания Skills», чтобы Claude помог создавать Skills. Попросите Claude создать Skill, и он сгенерирует правильно структурированное содержимое `SKILL.md` с подходящим frontmatter и телом.
   </Tip>

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

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

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

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

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

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

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

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

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

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

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

4. **Изучите рекомендации Claude A:** Claude A может порекомендовать реорганизацию, чтобы сделать правила более заметными, использование более сильных формулировок, например «ОБЯЗАТЕЛЬНО фильтровать» вместо «всегда фильтровать», или перестройку раздела рабочего процесса.

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

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

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

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

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

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

Итерируя над навыками, обращайте внимание на то, как 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.

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

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

````markdown
**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, перейдите к разделу [Чек-лист эффективных навыков](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/best-practices#checklist-for-effective-skills).

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

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

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

```python
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:**

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

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

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

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

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

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

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

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

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

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

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

<Frame>
  ![Включение исполняемых скриптов вместе с файлами инструкций](https://platform.claude.com/docs/ru/images/agent-skills-executable-scripts.svg)
</Frame>

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

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

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

Для большинства служебных скриптов предпочтительно выполнение, поскольку оно надёжнее и эффективнее. Подробнее о том, как работает выполнение скриптов, см. в следующем разделе [Среда выполнения](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/best-practices#runtime-environment).

**Пример:**

````markdown
## 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 их проанализировать:

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

<Note>
  В этом примере вам потребуется написать скрипт `pdf_to_images.py`.
</Note>

Возможности зрения 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` и убедитесь, что они доступны, по документации [инструмента выполнения кода](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/code-execution-tool).

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

Навыки выполняются в среде выполнения кода с доступом к файловой системе, командам bash и возможностям выполнения кода. Концептуальное объяснение этой архитектуры см. в разделе [Архитектура навыков](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#the-skills-architecture) обзора.

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

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

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` (обзор, указывает на справочные файлы)

  * `reference/`

    * `finance.md` (метрики выручки)
    * `sales.md` (данные воронки)
    * `product.md` (аналитика использования)

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

Полные сведения о технической архитектуре см. в разделе [Как работают навыки](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#how-skills-work) обзора навыков.

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

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

**Формат:** `ServerName:tool_name`

**Пример:**

```markdown
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.

### Не предполагайте, что инструменты установлены

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

````markdown
**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](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#skill-structure) в Agent Skills.

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

Держите тело `SKILL.md` в пределах 500 строк для оптимальной производительности. Если ваше содержимое превышает этот объём, разделите его на отдельные файлы, используя описанные ранее шаблоны постепенного раскрытия. Подробности архитектуры см. в разделе [Как работают Skills](https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/overview#how-skills-work).

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

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

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

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

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

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

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

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

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

<CardGroup cols={2}>
  <Card title="Начало работы с Agent Skills" icon="rocket" href="https://platform.claude.com/docs/ru/agents-and-tools/agent-skills/quickstart">
    Создайте свой первый навык
  </Card>

  <Card title="Использование навыков в Claude Code" icon="terminal" href="https://code.claude.com/docs/ru/skills">
    Создавайте навыки и управляйте ими в Claude Code
  </Card>

  <Card title="Использование навыков с API" icon="code" href="https://platform.claude.com/docs/ru/build-with-claude/skills-guide">
    Загружайте и используйте навыки программно
  </Card>
</CardGroup>
