Как превратить техническую книгу в навык для агента

Превращение технической книги в навык агента: что вы получаете

Чтобы превратить техническую книгу в навык агента, вы направляете конвертер на PDF, EPUB, экспорт DOCX или папку с внутренними документами, которыми вы уже владеете. Он создает каталог навыка: один входной файл, содержащий именованные фреймворки и индекс глав, и по одному файлу на каждую главу, которые агент считывает только тогда, когда ваш вопрос требует этого. Книга никогда не попадает в контекстное окно. Туда попадает только индекс.

Это задача, обратная написанию навыка агента с нуля, где вы кодируете процедуру, которую уже знаете. Здесь же знания существуют, но никто не может ими воспользоваться: 800-страничный PDF от поставщика или руководство, которое не открывали с тех пор, как уволился его автор. Работа заключается в сжатии и индексации. Если термин «навык» для вас нов, сначала прочитайте что такое навык агента на самом деле.

Конвертер, используемый здесь, — это book-to-skill, навык с лицензией MIT, который работает на вашей собственной машине. Текущий тег по состоянию на август 2026 года — v1.4.0. Структура, которую он создает, важнее самого инструмента, и в последнем разделе перед FAQ показано, как создать такую же структуру вручную.

Почему бюджет токенов определяет всю архитектуру

Книга, вставленная в контекстное окно, расходует полный объем токенов при каждом обращении к ней. Навык (skill) расходует объем своего входного файла один раз, плюс объем тех глав, к которым фактически обращается вопрос. Проект устанавливает бюджет для каждого генерируемого файла.

[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

Входной файл, SKILL.md, ограничен 4,000 токенами и содержит перечень используемых фреймворков и индекс глав. Каждый файл главы занимает около 1,000 токенов и хранится на диске до тех пор, пока не потребуется. Вспомогательные файлы имеют аналогичные ограничения: 1,500 токенов для glossary.md, 2,000 для patterns.md, 1,000 для cheatsheet.md.

Эти бюджеты соответствуют тому, как Claude Code фактически расходует контекст. description навыка находится в списке навыков, чтобы модель знала о его существовании. Тело навыка загружается при его вызове и остается в контексте до конца сессии, поэтому каждая строка во входном файле является постоянным расходом. Вспомогательные файлы загружаются только тогда, когда агент читает их, что делает файлы отдельных глав экономичными.

За числом токенов входного файла стоит более жесткое ограничение. Когда функция автосжатия (auto-compaction) суммирует длинную беседу, Claude Code повторно присоединяет последний вызов каждого навыка после сводки и сохраняет первые 5,000 токенов каждого из них в рамках общего бюджета в 25,000 токенов для всех повторно присоединенных навыков. Входной файл, который укладывается в 5,000 токенов, сохраняется после сжатия целиком. Входной файл объемом 20,000 токенов возвращается только в объеме первой четверти, и ничто не указывает на то, какие три четверти были утрачены.

Это и есть прогрессивное раскрытие информации: небольшой индекс, который всегда оправдывает свою стоимость, и основной объем материала, скрытый за дверью, которую агент открывает намеренно. Как Claude Code управляет контекстным окном содержит подробности остальной части этого учета.

Установка конвертера на VPS с фиксацией версии

Этот навык представляет собой git-репозиторий. Клонируйте его в директорию навыков (skills) используемого вами агента. Имя директории становится слэш-командой, поэтому путь клонирования не является вопросом предпочтений.

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch принимает тег, поэтому данная команда проверяет v1.4.0 и ничего более позднего. Фиксируйте версию, так как навык — это набор инструкций, которым следует ваш агент, а непроверенное изменение этих инструкций означает изменение того, что выполняется на вашем сервере. GitHub Copilot CLI считывает ~/.copilot/skills/, а Amp считывает ~/.agents/skills/.

Также существует вариант установки одной командой, npx skills add virgiliojr94/book-to-skill, которая загружает текущую версию. Используйте её для ознакомления с инструментом. Для всего, что вы запускаете повторно, используйте зафиксированный клон.

Теперь подтвердите, какие экстракторы установлены на сервере:

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check сообщает, какие экстракторы установлены, и выводит команду установки для каждого отсутствующего. Пакету требуется Python 3.9 или новее.

Если /book-to-skill не появляется в автодополнении после клонирования, перезапустите агента. Claude Code отслеживает директории навыков, которые существовали на момент запуска сессии, поэтому ~/.claude/skills/, созданный две минуты назад, ещё не отслеживается.

Какие экстракторы вам действительно нужны?

Ничего, кроме Python, не требуется, так как для каждого формата предусмотрен резервный вариант в стандартной библиотеке. Эти варианты работают хуже, а на небольшом сервере установка ненужных экстракторов — это пустая трата времени.

• pdftotext из пакета poppler-utils обрабатывает PDF с большим объемом текста практически мгновенно. Установите его с помощью sudo apt install poppler-utils.
• pypdf и pdfminer.six — это резервные Python-инструменты для PDF.
• docling предназначен для технических PDF, ценность которых заключается в таблицах и листингах кода. Проект оценивает его скорость примерно в 1.5 секунды на страницу.
• ebooklib вместе с beautifulsoup4 корректно считывают EPUB. Без них инструмент переключается на стандартный ридер zipfile.
• python-docx считывает DOCX, а striprtf — RTF.
• ebook-convert из состава Calibre требуется для файлов MOBI и AZW.
• ocrmypdf выполняет OCR (оптическое распознавание символов) для сканированных книг, в которых отсутствует текстовый слой.

В Ubuntu 24.04 обычный вызов pip3 install pypdf завершается с такой ошибкой:

error: externally-managed-environment

Это не поломка pip. Ubuntu и Debian помечают системный Python как управляемый через apt, поэтому pip отказывается вносить в него изменения. Есть два решения. sudo apt install poppler-utils устанавливает бинарный файл и вообще не требует pip, а pdftotext самостоятельно справляется с большинством PDF, содержащих текст. Для Python-экстракторов создайте виртуальное окружение и запускайте агент из него, чтобы python3, который вызывает навык, был тем самым интерпретатором, где установлены нужные пакеты.

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

Репозиторий объявляет дополнительные компоненты pdf, epub, docx, rtf, technical и all, где technical — это docling. На странице установки проекта также упоминается pip install "book-to-skill[pdf,epub,docx]", но по состоянию на август 2026 года это имя не опубликовано в PyPI, поэтому устанавливайте его из собственного локального репозитория, как описано выше.

Не устанавливайте docling, пока в нем не возникнет необходимость для конкретной книги. Он подтягивает стек машинного обучения, поэтому перед установкой проверьте наличие свободного места на диске, если у вас тариф с ограниченными ресурсами.

Запуск для папки с документами, включая headless-режим

Команда принимает файл, папку, glob-шаблон в кавычках или несколько путей сразу, за которыми может следовать имя навыка (skill). Работает всё, что можно разместить в одном каталоге, включая набор RFC (request for comments — документы, определяющие интернет-протоколы).

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

Заключайте glob-шаблон в кавычки, чтобы оболочка не раскрыла его до того, как он попадет в навык. Если указать команде путь к существующему каталогу навыка, новые источники будут добавлены в него, а не создадут второй навык.

Интерактивный запуск предполагает ответы на вопросы. Является ли материал техническим или насыщенным текстом — это определяет экстрактор. Нужна ли глубина для справок или для обучения — это определяет бюджет на главу. Как должен называться навык и в какой корневой каталог навыков его поместить. Перед генерацией также выводятся оценки количества токенов и времени, после чего система ожидает подтверждения.

В headless-режиме отвечать на вопросы некому. Навыки, вызываемые пользователем, работают в claude -p: вставьте slash-команду в строку запроса, и Claude Code раскроет её до начала выполнения. Поэтому отвечайте на вопросы в том же запросе.

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools предварительно одобряет инструменты, необходимые для запуска, так как запрос на разрешение без привязанного терминала приведет к тому, что выполнение никогда не завершится. Добавление --output-format json включает total_cost_usd в результат — это клиентская оценка, а не ваш счет.

Извлечение объединяет все источники во временном рабочем каталоге в /tmp до того, как их прочитает модель, а на последнем этапе выполнения этот каталог удаляется. Источник, который не удалось извлечь, пропускается, чтобы пакетная обработка не прерывалась. Это означает, что запуск может быть успешно завершен, даже если прочитано меньше файлов, чем вы предоставили. Сравните список файлов в итоговом отчете с тем, что находится в папке. Отсутствующая глава обычно означает отсутствие источника.

Используйте для запуска сервер, который вы готовы доверить агенту. В Безопасный запуск Claude Code на VPS рассматриваются вопросы прав доступа.

Куда сохранять результат, чтобы ваш агент по программированию его нашел

Созданный навык попадает в корневой каталог навыков. Важны два из них.

• ~/.claude/skills/<skill-name>/ — это личный каталог, доступный в любом проекте на данной машине.
• .claude/skills/<skill-name>/ — находится внутри репозитория и перемещается вместе с ним.

Внутри любого из них вы найдете SKILL.md, каталог chapters/ с одним файлом на каждую главу, а также вспомогательные файлы. Имя каталога является командой, поэтому ~/.claude/skills/platform-handbook/ дает вам /platform-handbook, и вы можете добавить после него тему или обычный вопрос.

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

Одни издержки растут с каждым добавленным навыком. Описание каждого навыка остается в списке навыков, чтобы модель могла принять решение о его использовании; суммарный текст описания обрезается до 1,536 символов на запись, а весь список в целом имеет ограничение по объему. Десять навыков по книгам означают десять описаний, конкурирующих за это место. Для тех навыков, которые вы всегда вызываете по имени, добавьте одну строку в сгенерированный frontmatter:

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

С помощью disable-model-invocation: true описание полностью исключается из контекста, при этом навык по-прежнему загружается в полном объеме, когда вы вводите /platform-handbook. Вы отказываетесь от автоматического обнаружения и получаете менее загруженное окно контекста.

Лицензирование: MIT распространяется на конвертер, а не на книгу

Будьте точны в этом вопросе, так как здесь проблема носит не технический характер.

• Лицензия MIT распространяется на код конвертера и определение его навыков. Она ничего не говорит о документе, который вы обрабатываете.
• Запуск конвертера для книги, которую вы приобрели, на оборудовании под вашим контролем — это создание заметок из вашей собственной копии.
• Публикация результата является распространением, и лицензия MIT на инструмент не дает вам права распространять что-либо, производное от чужой книги.
• Результат работы является производным произведением. Структура и основные выводы глав по-прежнему определяются первоисточником, а производное произведение регулируется авторским правом на этот источник.
• Навык, созданный из материала, который вы не имеете права распространять, должен оставаться на той машине, где он был создан. Не в публичном репозитории. Не в общем командном маркетплейсе.
• Публикуйте только тогда, когда источник принадлежит вам или имеет открытую лицензию: документацию, написанную вашей командой, или стандарт, условия которого разрешают распространение.

Инструмент спроектирован с учетом этого. Он не поставляет содержимое книг, извлечение данных выполняется локально, а этап публикации запрашивает видимость репозитория как отдельный вопрос, требующий явного ввода public или private, вместо автоматического определения. Рассматривайте этот запрос как решение по лицензированию, потому что именно им он и является.

Внутренние справочники создают вторую проблему. Они содержат учетные данные чаще, чем принято признавать, а конвертер превращает PDF, который никто не открывает, в файл, который ваш агент читает по запросу. Просматривайте сгенерированные файлы перед тем, как зафиксировать их в репозитории, и ознакомьтесь с сохранением секретов вне ваших AI-агентов.

Сколько стоит одна конвертация?

Приведенные ниже цифры являются собственными опубликованными измерениями проекта, а не нашими.

[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

Для 4 книг, измеренных в рамках проекта, стоимость одной конвертации составила от 0.88 до 1.42 долларов США, а для книги Pro Git — 1.23. Эти показатели были получены на модели Claude Sonnet 4.5, с подсчетом токенов из tiktoken с использованием cl100k_base, и опубликованы в docs/performance.md проекта по состоянию на август 2026 года. Ваши собственные показатели будут меняться в зависимости от используемой модели и цен.

Проект также фиксирует, что для ответа на один вопрос по навыку требуется в 24–51 раз меньше токенов, чем при вставке всей книги в контекст. Воспринимайте это как примерную экономию, а не как гарантию, так как результат зависит от конкретной книги и вопроса. Структурный вывод остается неизменным: за конвертацию платят один раз, а за дамп контекста приходится платить при каждом диалоге, требующем обращения к книге.

Почему не стоит просто вставлять PDF или создавать RAG-индекс?

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

Поиск, или RAG (retrieval augmented generation), выполняет поиск в момент запроса и возвращает фрагменты, соответствующие вашим словам. Это эффективно, когда вам нужна точная фраза. Это неэффективно, когда полезная информация представляет собой концепцию, распределенную по всей главе, так как ни один отдельный фрагмент не содержит ее целиком. Навык (skill) выполняет такое извлечение один раз, на этапе конвертации, и сохраняет структуру вместо набора фрагментов.

Честное ограничение: сгенерированный навык — это сжатое резюме с потерей данных, написанное моделью. Это учебное пособие, а первоисточник остается первоисточником. Когда точная формулировка имеет юридическую или протокольную значимость, используйте PDF и цитируйте его. В Сравнение навыков с MCP-серверами и файлами правил рассматривается область применения каждого подхода.

Режимы сбоев и сообщения об ошибках

Отсканированный PDF не дает результата. Экстрактор проверяет первые страницы на наличие текстового слоя и останавливается с пояснением, вместо того чтобы обрабатывать 400 страниц изображений. Сначала запустите ocrmypdf input.pdf output.pdf, а затем передайте ему полученный файл.

pip отказывается выполнять установку. error: externally-managed-environment в Ubuntu 24.04 означает, что apt защищает системный Python. Используйте виртуальное окружение, описанное выше, или установите poppler-utils и полностью откажитесь от использования pip.

Главы определяются неверно. Механизм обнаружения глав ищет явные заголовки, такие как Chapter 7 и их языковые варианты. Книга, в которой используются простые названия разделов или римские цифры, будет разделена некорректно. Решение заключается в том, чтобы явно указать, где начинаются главы, вместо того чтобы полагаться на автоматическое определение.

Команда не найдена. Если /book-to-skill отсутствует в автодополнении, это означает, что каталог skills был создан уже после начала вашей сессии. Перезапустите агент.

Docling работает слишком долго. При скорости примерно 1.5 секунды на страницу обработка большой книги занимает минуты процессорного времени. На общем сервере этот процесс конкурирует с другими запущенными сервисами. Ответьте "text-heavy" (текстовый контент), когда программа спросит о типе содержимого, или передайте флаг --mode text при самостоятельном запуске scripts/extract.py. --mode technical — это ответ, который выбирает docling.

Исходный файл бесследно исчезает. Файл, который не удалось прочитать, пропускается, чтобы пакетная обработка могла завершиться. В итоге программа сообщает об успешном выполнении для меньшего количества источников, чем было передано изначально. Единственное место, где это отражено — инвентаризация файлов в итоговом отчете.

Примените тот же шаблон вручную

Инструмент — это лишь удобство. Переносимой частью является структура, а текстовый редактор позволяет создать её для любых справочных материалов, которыми вы владеете.

1. Создайте один входной файл и держите его рядом с токенами 4,000, на которые ориентируется конвертер. Внесите в него именованные концепции с их точными формулировками, а также индекс, перечисляющий каждый файл с деталями и темы, которые в этом файле содержатся.
2. Разбейте материал на файлы объёмом примерно 1,000 токенов, по одной теме на каждый, и называйте их так, чтобы имя файла само говорило о его содержимом.
3. Опишите каждый из этих файлов во входном файле, добавив предложение о том, когда именно его следует читать.

Шаг 3 — это то, что люди часто пропускают, хотя именно он заставляет шаблон работать. Агент выбирает, какой файл открыть, читая индекс, поэтому файл, не описанный в индексе, агент никогда не откроет. Индекс — это и есть продукт, а файлы глав — лишь хранилище.

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

FAQ

Могу ли я опубликовать навык, созданный на основе купленной книги?

Нет, если лицензия книги не разрешает распространение. Лицензия MIT на конвертер распространяется только на код самого конвертера, а не на материал, который вы в него загружаете; созданный навык является производной работой от книги. Храните его в ~/.claude/skills/ на своем локальном компьютере. Публикация допустима для документации, написанной вами самостоятельно, или для материалов с открытой лицензией. Инструмент отдельно запрашивает уровень видимости репозитория, принимая только явные public или private, поэтому решение остается осознанным.

Нужен ли мне docling или достаточно pdftotext?

pdftotext из состава poppler-utils достаточно для обычного текста, и работает он практически мгновенно. Устанавливайте docling, если ценность книги заключается в таблицах и листингах кода, так как простые текстовые экстракторы теряют именно эти данные. Платой за это является скорость: проект оценивает работу docling примерно в 1.5 секунды на страницу, поэтому обработка руководства на 300 страниц займет несколько минут процессорного времени на VPS.

Почему pip выдает ошибку externally-managed-environment на моем VPS?

В Ubuntu 24.04 и актуальных версиях Debian системный Python помечен как управляемый через apt, поэтому pip отказывается устанавливать в него пакеты и выводит error: externally-managed-environment. Создайте виртуальное окружение с помощью python3 -m venv ~/.venvs/book-to-skill, активируйте его, установите туда экстракторы, а затем запускайте своего агента из той же оболочки. Навык вызывает python3, поэтому он использует тот интерпретатор, который находится в вашем PATH — в данном случае, интерпретатор из виртуального окружения.

Почему созданный мной навык не отображается как slash-команда?

Есть две причины. Имя команды берется из имени каталога, поэтому навык должен находиться в ~/.claude/skills/<name>/SKILL.md или .claude/skills/<name>/SKILL.md, а файл SKILL.md должен быть назван именно так. Если путь указан верно, перезапустите агента. Claude Code отслеживает изменения внутри каталогов навыков, которые он уже мониторит, но каталог навыков, созданный после начала сессии, не попадает под наблюдение автоматически.