Лучшие практики создания 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. Затем вы можете использовать код ниже...

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

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

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

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

```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. Используйте когда пользователь просит помощь в написании сообщений коммитов или просмотре поставленных изменений.

description: Помогает с документами

description: Обрабатывает данные

description: Делает что-то с файлами

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

# Обработка DOCX

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

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

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

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

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

# SKILL.md
См. [advanced.md](advanced.md)...

# advanced.md
См. [details.md](details.md)...

# details.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. Протестируйте выходной документ

Если вы делаете это до августа 2025, используйте старый API.
После августа 2025 используйте новый API.

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

Используйте конечную точку 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 в четком, читаемом формате"
  ]
}

**Плохой пример: Слишком много выборов** (запутанно):
"Вы можете использовать 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 ''

def process_file(path):
    # Просто сбой и позвольте Claude разобраться
    return open(path).read()

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

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

TIMEOUT = 47  # Почему 47?
RETRIES = 5   # Почему 5?

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

**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")
```"