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

## Извлечение текста из PDF

Используйте pdfplumber для извлечения текста:

```python
import pdfplumber

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

## Извлечение текста из PDF

PDF (Portable Document Format) — это распространенный формат файлов, который содержит
текст, изображения и другое содержимое. Для извлечения текста из PDF вам потребуется
использовать библиотеку. Доступно много библиотек для обработки PDF, но мы
рекомендуем pdfplumber, потому что она легко использовать и она хорошо справляется с большинством случаев.
Сначала вам нужно установить ее с помощью pip. Затем вы можете использовать код ниже...

## Процесс проверки кода

Анализируйте структуру и организацию кода
Проверьте на потенциальные ошибки или граничные случаи
Предложите улучшения для читаемости и поддерживаемости
Проверьте соответствие соглашениям проекта

## Создание отчета

Используйте этот шаблон и настройте по мере необходимости:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Обработка данных
    # Создание вывода в указанном формате
    # Опционально включение визуализаций
```

## Миграция базы данных

Запустите ровно этот скрипт:

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

Не изменяйте команду и не добавляйте дополнительные флаги.

description: Извлекает текст и таблицы из файлов PDF, заполняет формы, объединяет документы. Используйте при работе с файлами PDF или когда пользователь упоминает PDF, формы или извлечение документов.

description: Анализирует электронные таблицы Excel, создает сводные таблицы, создает диаграммы. Используйте при анализе файлов Excel, электронных таблиц, табличных данных или файлов .xlsx.

description: Создает описательные сообщения коммитов путем анализа git diffs. Используйте когда пользователь просит помощь в написании сообщений коммитов или просмотре поставленных изменений.

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

---
name: pdf-processing
description: Извлекает текст и таблицы из файлов PDF, заполняет формы и объединяет документы. Используйте при работе с файлами PDF или когда пользователь упоминает PDF, формы или извлечение документов.
---

# Обработка PDF

## Быстрый старт

Извлеките текст с помощью pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Продвинутые функции

**Заполнение форм**: См. [FORMS.md](FORMS.md) для полного руководства
**Справка API**: См. [REFERENCE.md](REFERENCE.md) для всех методов
**Примеры**: См. [EXAMPLES.md](EXAMPLES.md) для распространенных паттернов

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

SKILL.md

# Анализ данных BigQuery

## Доступные наборы данных

**Финансы**: Доход, ARR, выставление счетов → См. [reference/finance.md](reference/finance.md)
**Продажи**: Возможности, конвейер, учетные записи → См. [reference/sales.md](reference/sales.md)
**Продукт**: Использование API, функции, внедрение → См. [reference/product.md](reference/product.md)
**Маркетинг**: Кампании, атрибуция, электронная почта → См. [reference/marketing.md](reference/marketing.md)

## Быстрый поиск

Найдите конкретные метрики с помощью grep:

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

# Обработка DOCX

## Создание документов

Используйте docx-js для новых документов. См. [DOCX-JS.md](DOCX-JS.md).

## Редактирование документов

Для простых правок измените XML напрямую.

**Для отслеживаемых изменений**: См. [REDLINING.md](REDLINING.md)
**Для деталей OOXML**: См. [OOXML.md](OOXML.md)

# SKILL.md

**Базовое использование**: [инструкции в SKILL.md]
**Продвинутые функции**: См. [advanced.md](advanced.md)
**Справка API**: См. [reference.md](reference.md)
**Примеры**: См. [examples.md](examples.md)

# Справка API

## Содержание
- Аутентификация и настройка
- Основные методы (создание, чтение, обновление, удаление)
- Продвинутые функции (пакетные операции, вебхуки)
- Паттерны обработки ошибок
- Примеры кода

## Аутентификация и настройка
...

## Основные методы
...

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

Скопируйте этот контрольный список и отслеживайте ваш прогресс:

```
Прогресс исследования:
- [ ] Шаг 1: Прочитайте все исходные документы
- [ ] Шаг 2: Определите ключевые темы
- [ ] Шаг 3: Перекрестно ссылайтесь на утверждения
- [ ] Шаг 4: Создайте структурированное резюме
- [ ] Шаг 5: Проверьте цитаты
```

**Шаг 1: Прочитайте все исходные документы**

Просмотрите каждый документ в каталоге `sources/`. Отметьте основные аргументы и подтверждающие доказательства.

**Шаг 2: Определите ключевые темы**

Ищите паттерны в источниках. Какие темы повторяются? Где источники согласны или не согласны?

**Шаг 3: Перекрестно ссылайтесь на утверждения**

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

**Шаг 4: Создайте структурированное резюме**

Организуйте результаты по темам. Включите:
- Основное утверждение
- Подтверждающие доказательства из источников
- Противоречивые точки зрения (если есть)

**Шаг 5: Проверьте цитаты**

Проверьте, что каждое утверждение ссылается на правильный исходный документ. Если цитаты неполные, вернитесь к шагу 3.

## Рабочий процесс заполнения форм PDF

Скопируйте этот контрольный список и отмечайте элементы по мере их завершения:

```
Прогресс задачи:
- [ ] Шаг 1: Анализируйте форму (запустите analyze_form.py)
- [ ] Шаг 2: Создайте сопоставление полей (отредактируйте fields.json)
- [ ] Шаг 3: Проверьте сопоставление (запустите validate_fields.py)
- [ ] Шаг 4: Заполните форму (запустите fill_form.py)
- [ ] Шаг 5: Проверьте вывод (запустите verify_output.py)
```

**Шаг 1: Анализируйте форму**

Запустите: `python scripts/analyze_form.py input.pdf`

Это извлекает поля формы и их местоположения, сохраняя в `fields.json`.

**Шаг 2: Создайте сопоставление полей**

Отредактируйте `fields.json`, чтобы добавить значения для каждого поля.

**Шаг 3: Проверьте сопоставление**

Запустите: `python scripts/validate_fields.py fields.json`

Исправьте любые ошибки валидации перед продолжением.

**Шаг 4: Заполните форму**

Запустите: `python scripts/fill_form.py input.pdf fields.json output.pdf`

**Шаг 5: Проверьте вывод**

Запустите: `python scripts/verify_output.py output.pdf`

Если проверка не пройдена, вернитесь к шагу 2.

## Процесс проверки содержимого

1. Создайте ваше содержимое, следуя руководствам в STYLE_GUIDE.md
2. Проверьте против контрольного списка:
   - Проверьте консистентность терминологии
   - Проверьте, что примеры следуют стандартному формату
   - Подтвердите, что все требуемые разделы присутствуют
3. Если найдены проблемы:
   - Отметьте каждую проблему с конкретной ссылкой на раздел
   - Пересмотрите содержимое
   - Проверьте контрольный список снова
4. Продолжайте только когда все требования выполнены
5. Завершите и сохраните документ

## Процесс редактирования документа

1. Внесите ваши правки в `word/document.xml`
2. **Проверьте немедленно**: `python ooxml/scripts/validate.py unpacked_dir/`
3. Если валидация не пройдена:
   - Внимательно прочитайте сообщение об ошибке
   - Исправьте проблемы в XML
   - Запустите валидацию снова
4. **Продолжайте только когда валидация пройдена**
5. Пересоберите: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Протестируйте выходной документ

## Текущий метод

Используйте конечную точку API v2: `api.example.com/v2/messages`

## Старые паттерны

<details>
<summary>Устаревший API v1 (устарел 2025-08)</summary>

API v1 использовал: `api.example.com/v1/messages`

Эта конечная точка больше не поддерживается.
</details>

## Структура отчета

ВСЕГДА используйте эту точную структуру шаблона:

```markdown
# [Название анализа]

## Резюме руководителя
[Однопараграфный обзор ключевых результатов]

## Ключевые результаты
- Результат 1 с поддерживающими данными
- Результат 2 с поддерживающими данными
- Результат 3 с поддерживающими данными

## Рекомендации
1. Конкретная действенная рекомендация
2. Конкретная действенная рекомендация
```

## Структура отчета

Вот разумный формат по умолчанию, но используйте ваше лучшее суждение на основе анализа:

```markdown
# [Название анализа]

## Резюме руководителя
[Обзор]

## Ключевые результаты
[Адаптируйте разделы на основе того, что вы обнаружите]

## Рекомендации
[Адаптируйте к конкретному контексту]
```

Адаптируйте разделы по мере необходимости для конкретного типа анализа.

## Формат сообщения коммита

Создавайте сообщения коммитов, следуя этим примерам:

**Пример 1:**
Ввод: Добавлена аутентификация пользователя с токенами JWT
Вывод:
```
feat(auth): реализуйте аутентификацию на основе JWT

Добавьте конечную точку входа и промежуточное ПО валидации токена
```

**Пример 2:**
Ввод: Исправлена ошибка, когда даты отображались неправильно в отчетах
Вывод:
```
fix(reports): исправьте форматирование даты в преобразовании часовых поясов

Используйте временные метки UTC последовательно при создании отчетов
```

**Пример 3:**
Ввод: Обновлены зависимости и переработана обработка ошибок
Вывод:
```
chore: обновите зависимости и переработайте обработку ошибок

- Обновите lodash до 4.17.21
- Стандартизируйте формат ответа об ошибке на всех конечных точках
```

Следуйте этому стилю: type(scope): краткое описание, затем подробное объяснение.

## Рабочий процесс модификации документа

1. Определите тип модификации:

   **Создание нового содержимого?** → Следуйте "Рабочему процессу создания" ниже
   **Редактирование существующего содержимого?** → Следуйте "Рабочему процессу редактирования" ниже

2. Рабочий процесс создания:
   - Используйте библиотеку docx-js
   - Создайте документ с нуля
   - Экспортируйте в формат .docx

3. Рабочий процесс редактирования:
   - Распакуйте существующий документ
   - Измените XML напрямую
   - Проверьте после каждого изменения
   - Пересоберите при завершении

{
  "skills": ["pdf-processing"],
  "query": "Извлеките весь текст из этого файла PDF и сохраните его в output.txt",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Успешно читает файл PDF, используя подходящую библиотеку обработки PDF или инструмент командной строки",
    "Извлекает текстовое содержимое со всех страниц в документе без пропуска каких-либо страниц",
    "Сохраняет извлеченный текст в файл с именем output.txt в четком, читаемом формате"
  ]
}

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

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

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

Используйте 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 на основе реального поведения агента, а не предположений.

**Плохой пример: Слишком много выборов** (запутанно):
"Вы можете использовать pypdf, или pdfplumber, или PyMuPDF, или pdf2image, или..."

**Хороший пример: Предоставьте значение по умолчанию** (с выходом):
"Используйте pdfplumber для извлечения текста:
```python
import pdfplumber
```

Для отсканированных PDF, требующих OCR, используйте pdf2image с pytesseract вместо этого."

def process_file(path):
    """Обработайте файл, создав его, если он не существует."""
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        # Создайте файл с содержимым по умолчанию вместо сбоя
        print(f"Файл {path} не найден, создание по умолчанию")
        with open(path, 'w') as f:
            f.write('')
        return ''
    except PermissionError:
        # Предоставьте альтернативу вместо сбоя
        print(f"Не могу получить доступ к {path}, используя значение по умолчанию")
        return ''

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

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

## Служебные скрипты

**analyze_form.py**: Извлеките все поля формы из PDF

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

Формат вывода:
```json
{
  "field_name": {"type": "text", "x": 100, "y": 200},
  "signature": {"type": "sig", "x": 150, "y": 500}
}
```

**validate_boxes.py**: Проверьте на перекрывающиеся ограничивающие коробки

```bash
python scripts/validate_boxes.py fields.json
# Возвращает: "OK" или список конфликтов
```

**fill_form.py**: Примените значения полей к PDF

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

## Анализ макета формы

1. Преобразуйте PDF в изображения:
   ```bash
   python scripts/pdf_to_images.py form.pdf
   ```

2. Анализируйте каждое изображение страницы для определения полей формы
3. Claude может видеть местоположения и типы полей визуально

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

Используйте инструмент BigQuery:bigquery_schema для получения схем таблиц.
Используйте инструмент GitHub:create_issue для создания проблем.

**Плохой пример: Предполагает установку**:
"Используйте библиотеку pdf для обработки файла."

**Хороший пример: Явно о зависимостях**:
"Установите требуемый пакет: `pip install pypdf`

Затем используйте его:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"

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

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

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

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

Установите надлежащие степени свободы

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

Структура Skill

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

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

Паттерны прогрессивного раскрытия

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

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

Паттерн 2: Организация по доменам

Паттерн 3: Условные детали

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

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

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

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

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

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

Избегайте информации, чувствительной ко времени

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

Распространенные паттерны

Паттерн шаблона

Паттерн примеров

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

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

Создайте оценки в первую очередь

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

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

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

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

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

Advanced: Skills с исполняемым кодом

Решайте, не избегайте

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

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

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

Упакуйте зависимости

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

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

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

Технические заметки

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

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

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

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

Код и скрипты

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

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