SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor

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

Узнайте, как конвертировать PDF или EPUB в индексируемый навык для кодинг-агента. Инструкция по установке, управлению токенами и запуску в headless режиме для вашей документации.

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

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

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

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

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

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

ГрафикDocumented token budget per generated file, book-to-skill v1.4.0
Данные, на которых построен график
[
  {
    "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 сообщает, какие экстракторы установлены, и выводит инструкции по установке для отсутствующих: одну объединенную команду pip для недостающих пакетов Python и подсказку для каждого отсутствующего системного инструмента. Пакету требуется Python 3.9 или новее.

Если /book-to-skill не появляется в автодополнении после клонирования, выполните /reload-skills или перезапустите агента. 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

В зафиксированной версии v1.4.0 объявлены дополнительные компоненты pdf, epub, docx, rtf, technical и all, где technical — это docling. На странице установки проекта также описана автономная установка из командной строки напрямую из GitHub: pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git", за которой следует book-to-skill --check для вывода списка установленных экстракторов. Это не требует релиза в PyPI, но устанавливает ветку по умолчанию, а не v1.4.0, и предоставляет только команду экстрактора, а не навык /book-to-skill. Для настройки с фиксацией версий устанавливайте пакет из собственной локальной копии, как описано выше. Простая команда pip install book-to-skill не сработает, так как по состоянию на октябрь 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-шаблон в кавычки, чтобы оболочка (shell) не раскрыла его до того, как он попадет в навык. Если указать команде существующий каталог навыка, новые источники будут добавлены в него, а не создадут второй навык.

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

В 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 на инструмент не дает вам права распространять что-либо, производное от чужой книги.
  • Выходной файл является производным произведением. Структура и основные идеи глав по-прежнему определяются первоисточником, а производное произведение регулируется авторским правом на этот источник.
  • Навык, созданный на основе материала, который вы не можете распространять, должен оставаться на той машине, где он был создан. Не в публичном репозитории. Не в общем командном маркетплейсе.
  • Публикуйте контент, если источник принадлежит вам или имеет открытую лицензию: документацию, которую написала ваша команда, или стандарт, условия которого разрешают распространение.

Инструмент спроектирован с учетом этого. Он не поставляет содержимое книг, а извлечение данных выполняется локально. Закрепленный v1.4.0 выводит только необязательную строку gh skill publish и никогда не спрашивает о видимости, поэтому решение полностью остается за вами. В ветку по умолчанию с тех пор был добавлен этап публикации, который запрашивает видимость репозитория отдельным вопросом из одного слова и создает публичный репозиторий только в том случае, если ответом является слово public; любой другой ответ приводит к созданию приватного репозитория. Рассматривайте этот этап как принятие решения о лицензировании, потому что это именно то, чем он является.

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

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

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

ГрафикCost to convert one full-length book, as published by the project
Данные, на которых построен график
[
  {
    "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 и их языковые варианты, а также распознает римские цифры, например Chapter IV или IV. Title. Книга, в которой используются простые ненумерованные заголовки разделов, будет разделена некорректно. Чтобы исправить это, укажите при запуске, где начинаются главы, вместо того чтобы полагаться на автоматическое определение.

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

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

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

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

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

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

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

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

FAQ

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

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

Нужен ли мне 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, а это теперь интерпретатор из виртуального окружения.

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

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

Была ли эта статья полезной?