Проблема: «Шум» в контексте и галлюцинации
Традиционные методы работы с большими техническими книгами в AI-интерфейсах неэффективны. Попытка загрузить весь PDF в контекст приводит к переполнению окна токенов, а агенты часто «галлюцинируют», ссылаясь на несуществующие страницы. Инструмент book-to-skill от разработчика virgiliojr94 решает эту проблему, преобразуя неструктурированные документы (PDF, EPUB, DOCX) в формат Agent Skills (стандарт SKILL.md), который поддерживается GitHub Copilot CLI, Amp и Claude Code.
Метрика эффективности: Discovery Loop Tax
Ключевое преимущество — отказ от так называемого «налога на обнаружение» (Discovery Loop Tax). Обычный PDF-агент при каждом запросе заново сканирует оглавление и навигацию, что требует огромных затрат токенов. book-to-skill оплачивает эту стоимость структурирования один раз при конвертации. В результате, для ответа на один вопрос требуется в 24–51 раз меньше токенов, чем при прямой загрузке книги в контекст. Это измерено на реальных технических книгах (см. docs/performance.md в репозитории).
Архитектура сгенерированного навыка
Инструмент создает не просто резюме, а структурированную базу знаний. Файлы глав загружаются «по требованию» (on-demand), поэтому они не занимают место в контексте, пока вы не запросите конкретную тему. Ниже приведена структура и примерный объем генерируемых файлов:
| Файл | Назначение | Примерный размер |
|---|---|---|
SKILL.md |
Базовые ментальные модели + индекс глав | ~4,000 токенов |
chapters/ch01-*.md |
Один файл на главу, загружается по запросу | ~1,000 токенов/глава |
glossary.md |
Алфавитный список терминов со ссылками на главы | ~1,500 токенов |
patterns.md |
Техники, алгоритмы и паттерны проектирования | ~2,000 токенов |
cheatsheet.md |
Таблицы решений и быстрые справочные правила | ~1,000 токенов |
Поддержка форматов и извлечение данных
Инструмент использует детерминированный Python-экстрактор, который автоматически выбирает оптимальный инструмент в зависимости от типа документа. Для технических книг с кодом и таблицами рекомендуется docling (~1.5 сек/страница), сохраняющий структуру Markdown. Для текстовых книг быстрее работает pdftotext (poppler). Скан-изображения требуют предварительного OCR через ocrmypdf.
Применение за пределами книг
Хотя название указывает на книги, инструмент эффективен для любых структурированных текстов, которые вы читаете повторно:
- Внутренняя документация: Архитектурные решения (ADR), runbooks и гайды по онбордингу.
- Дизайн-системы: Гайды по тону голоса (tone-of-voice) и принципы компонентов.
- Исследования: Кластеры научных статей и заметки, объединенные в единый навык.
- Стандарты: RFC, контракты API и документы соответствия.
Установка и использование
Установка кросс-агентного CLI-инструмента выполняется одной командой:
npx skills add virgiliojr94/book-to-skill
После установки вы можете конвертировать любой файл или папку:
/book-to-skill ./my-book.pdf
Готовый навык сохраняется в директории агента (например, ~/.copilot/skills/ или ~/.claude/skills/). Для взаимодействия достаточно ввести команду вида /your-book-slug replication, и агент прочитает нужную главу из реальной структуры, а не будет галлюцинировать.
Источник: Github ↗