MessagesНавыки

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

Узнайте, как писать эффективные Skills, которые Claude сможет обнаруживать и успешно использовать.

Хорошие 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

Analyze the code structure and organization
Check for potential bugs or edge cases
Suggest improvements for readability and maintainability
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 ровно одно поле описания. Описание критически важно для выбора 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 к подробным материалам по мере необходимости, подобно оглавлению в руководстве по адаптации. Объяснение того, как работает «progressive disclosure» (постепенное раскрытие), см. в разделе Как работают Skills обзора.

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

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

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

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

Простой файл SKILL.md, показывающий YAML frontmatter и тело в формате markdown

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

Включение дополнительных справочных файлов, таких как reference.md и forms.md.

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

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

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

---
name: pdf-processing
description: 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 (обзор и навигация)
- reference/
  - finance.md (выручка, метрики биллинга)
  - sales.md (возможности, воронка)
  - product.md (использование API, функции)
  - marketing.md (кампании, атрибуция)

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

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

# 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

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

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

Шаблон с образцом

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

Для строгих требований (например, ответы 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 решает реальные проблемы, а не документирует воображаемые.

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

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

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

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

{
  "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:

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

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

Модели Claude изначально понимают формат и структуру Skill. Вам не нужны специальные системные подсказки или skill «написания skills», чтобы Claude помог создавать Skills. Просто попросите Claude создать Skill, и он сгенерирует правильно структурированное содержимое SKILL.md с подходящим frontmatter и телом.
Проверьте на лаконичность: убедитесь, что Claude A не добавил ненужных объяснений. Попросите: «Убери объяснение того, что означает win rate, — Claude это уже знает».
Улучшите информационную архитектуру: попросите Claude A организовать содержимое эффективнее. Например: «Организуй это так, чтобы схема таблицы была в отдельном справочном файле. Позже мы можем добавить больше таблиц».
Протестируйте на похожих задачах: используйте Skill с Claude B (свежим экземпляром с загруженным Skill) на связанных сценариях использования. Наблюдайте, находит ли Claude B нужную информацию, правильно ли применяет правила и успешно ли справляется с задачей.
Итерируйте на основе наблюдений: если Claude B испытывает трудности или что-то упускает, вернитесь к Claude A с конкретикой: «Когда Claude использовал этот Skill, он забыл отфильтровать по дате для Q4. Стоит ли добавить раздел о шаблонах фильтрации по дате?»

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

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

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

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

Пример наблюдения: «Когда я попросил Claude B подготовить региональный отчёт о продажах, он написал запрос, но забыл отфильтровать тестовые аккаунты, хотя Skill упоминает это правило».
Вернитесь к Claude A за улучшениями: поделитесь текущим SKILL.md и опишите, что вы наблюдали. Спросите: «Я заметил, что Claude B забыл отфильтровать тестовые аккаунты, когда я попросил региональный отчёт. Skill упоминает фильтрацию, но, возможно, недостаточно заметно?»
Рассмотрите предложения Claude A: Claude A может предложить реорганизацию, чтобы сделать правила заметнее, использование более сильных формулировок, таких как «ОБЯЗАТЕЛЬНО фильтровать» вместо «всегда фильтровать», или перестройку раздела рабочего процесса.
Примените и протестируйте изменения: обновите Skill с доработками Claude A, затем снова протестируйте с Claude B на похожих запросах
Повторяйте на основе использования: продолжайте этот цикл «наблюдение — доработка — тестирование» по мере столкновения с новыми сценариями. Каждая итерация улучшает Skill на основе реального поведения агента, а не предположений.

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

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

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

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

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

Включение исполняемых скриптов вместе с файлами инструкций

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

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

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

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

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

Пример:

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

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

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

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

Если ваш Skill использует инструменты MCP (Model Context Protocol), всегда используйте полностью квалифицированные имена инструментов, чтобы избежать ошибок «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-тегов

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

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

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

Чек-лист эффективных Skills

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

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

Код и скрипты

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

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

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

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

Начало работы с Agent Skills

Создайте свой первый Skill

Использование Skills в Claude Code

Создавайте Skills и управляйте ими в Claude Code

Использование Skills с API

Загружайте и используйте Skills программно

Was this page helpful?

MessagesНавыки

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

Узнайте, как писать эффективные Skills, которые Claude сможет обнаруживать и успешно использовать.

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

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

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

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

Предположение по умолчанию: 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

Analyze the code structure and organization
Check for potential bugs or edge cases
Suggest improvements for readability and maintainability
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 (быстрая, экономичная): даёт ли Skill достаточно указаний?
Claude Sonnet (сбалансированная): является ли Skill понятным и эффективным?
Claude Opus (мощные рассуждения): избегает ли Skill избыточных объяснений?

Структура 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

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

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

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 в пределах 500 строк для оптимальной производительности
Разделяйте содержимое на отдельные файлы при приближении к этому пределу
Используйте следующие шаблоны для эффективной организации инструкций, кода и ресурсов

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

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

Простой файл SKILL.md, показывающий YAML frontmatter и тело в формате markdown

Включение дополнительных справочных файлов, таких как reference.md и forms.md.

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

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

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

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

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

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

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

# 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 только тогда, когда пользователю нужны эти функции.

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

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

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

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

Пример:

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

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

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

Пример 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.

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

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

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

Пример 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

Пример 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

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

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

Шаблон с образцом

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

Для строгих требований (например, ответы 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

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

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

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

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

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

{
  "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:

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

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

Модели Claude изначально понимают формат и структуру Skill. Вам не нужны специальные системные подсказки или skill «написания skills», чтобы Claude помог создавать Skills. Просто попросите Claude создать Skill, и он сгенерирует правильно структурированное содержимое SKILL.md с подходящим frontmatter и телом.
Проверьте на лаконичность: убедитесь, что Claude A не добавил ненужных объяснений. Попросите: «Убери объяснение того, что означает win rate, — Claude это уже знает».
Улучшите информационную архитектуру: попросите Claude A организовать содержимое эффективнее. Например: «Организуй это так, чтобы схема таблицы была в отдельном справочном файле. Позже мы можем добавить больше таблиц».
Протестируйте на похожих задачах: используйте Skill с Claude B (свежим экземпляром с загруженным Skill) на связанных сценариях использования. Наблюдайте, находит ли Claude B нужную информацию, правильно ли применяет правила и успешно ли справляется с задачей.
Итерируйте на основе наблюдений: если Claude B испытывает трудности или что-то упускает, вернитесь к Claude A с конкретикой: «Когда Claude использовал этот Skill, он забыл отфильтровать по дате для Q4. Стоит ли добавить раздел о шаблонах фильтрации по дате?»

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

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

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

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

Пример наблюдения: «Когда я попросил Claude B подготовить региональный отчёт о продажах, он написал запрос, но забыл отфильтровать тестовые аккаунты, хотя Skill упоминает это правило».
Вернитесь к Claude A за улучшениями: поделитесь текущим SKILL.md и опишите, что вы наблюдали. Спросите: «Я заметил, что Claude B забыл отфильтровать тестовые аккаунты, когда я попросил региональный отчёт. Skill упоминает фильтрацию, но, возможно, недостаточно заметно?»
Рассмотрите предложения Claude A: Claude A может предложить реорганизацию, чтобы сделать правила заметнее, использование более сильных формулировок, таких как «ОБЯЗАТЕЛЬНО фильтровать» вместо «всегда фильтровать», или перестройку раздела рабочего процесса.
Примените и протестируйте изменения: обновите Skill с доработками Claude A, затем снова протестируйте с Claude B на похожих запросах
Повторяйте на основе использования: продолжайте этот цикл «наблюдение — доработка — тестирование» по мере столкновения с новыми сценариями. Каждая итерация улучшает Skill на основе реального поведения агента, а не предположений.

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

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

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

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

Неожиданными путями исследования: читает ли Claude файлы в порядке, которого вы не ожидали? Это может указывать на то, что ваша структура не так интуитивна, как вы думали
Упущенными связями: не переходит ли Claude по ссылкам на важные файлы? Возможно, ваши ссылки должны быть более явными или заметными
Чрезмерной опорой на определённые разделы: если Claude многократно читает один и тот же файл, подумайте, не должно ли это содержимое находиться в основном SKILL.md
Игнорируемым содержимым: если 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."

Продвинутый уровень: 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()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пути к файлам важны: 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 (аналитика использования)

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

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

Формат: 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-тегов

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

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

Чек-лист эффективных Skills

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

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

Код и скрипты

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

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

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

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

Начало работы с Agent Skills

Создайте свой первый Skill

Использование Skills в Claude Code

Создавайте Skills и управляйте ими в Claude Code

Использование Skills с API

Загружайте и используйте Skills программно

Was this page helpful?

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

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

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

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

Структура Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаблон с образцом

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Структура Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаблон с образцом

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Структура Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаблон с образцом

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Чек-лист эффективных Skills

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

Код и скрипты

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

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

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

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

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

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

Структура Skill

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаблон с образцом

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

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

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

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

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

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

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

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

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

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