Як перетворити технічну книгу на agent skill
Дізнайтеся, як перетворити PDF, EPUB або каталог документів на agent skill: встановлення book-to-skill v1.4.0, ліміт token, headless-запуски та ліцензія MIT.
Перетворення технічної книги на agent skill: що ви отримаєте
Щоб перетворити технічну книгу на agent skill, передайте конвертеру PDF, EPUB, експорт DOCX або каталог внутрішніх документів, якими ви вже володієте. Він створить каталог skill: один головний файл із переліченими framework і покажчиком розділів, а також окремий файл для кожного розділу. Agent читає ці файли лише тоді, коли запит цього потребує. Книга не потрапляє у вікно контексту. Покажчик потрапляє.
Це завдання, протилежне до написання agent skill з нуля, коли ви кодуєте процедуру, яку вже знаєте. Тут знання існують, але ніхто не може ними скористатися: це може бути PDF постачальника на 800 сторінок або посібник, який не відкривали відтоді, як його автор залишив компанію. Основна робота полягає у стисканні та індексації. Якщо поняття skill для вас нове, спочатку прочитайте що таке agent skill насправді.
У цьому матеріалі використовується конвертер book-to-skill — skill з ліцензією MIT, який працює на вашій машині. Поточний tag станом на October 2026 — v1.4.0. Структура, яку він створює, важливіша за сам інструмент. В останньому розділі перед FAQ показано, як створити таку саму структуру вручну.
Чому бюджет токенів визначає всю структуру
Книга, вставлена у вікно контексту, щоразу повністю враховується в кожній розмові, якій вона потрібна. Skill завантажує свій entry file один раз, а потім — лише ті розділи, яких безпосередньо стосується запит. Проєкт визначає бюджет для кожного створюваного файла.
Дані, на яких побудовано графік
[
{
"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"
}
]Для entry file, SKILL.md, встановлено обмеження 4,000 токенів. Він містить названі фреймворки та індекс розділів. Обсяг кожного файла розділу становить приблизно 1,000 токенів. Такий файл зберігається на диску, доки його не буде запитано. Допоміжні файли мають подібний обсяг: 1,500 токенів для glossary.md, 2,000 для patterns.md і 1,000 для cheatsheet.md.
Ці бюджети відповідають тому, як Claude Code фактично використовує контекст. Поле description skill відображається у списку skill, щоб модель знала про його наявність. Вміст завантажується під час виклику skill і після цього залишається в контексті до завершення сеансу. Тому кожен рядок entry file створює повторні витрати. Допоміжні файли завантажуються лише тоді, коли агент їх читає. Саме тому окремі файли розділів потребують мало ресурсів.
За обмеженням для entry file стоїть жорсткіший ліміт. Коли auto-compaction узагальнює довгу розмову, Claude Code повторно приєднує до узагальнення останній виклик кожного skill і зберігає перші 5,000 токенів кожного з них. Для всіх повторно приєднаних skill діє спільний бюджет у 25,000 токенів. Якщо entry file вміщується в 5,000 токенів, після compaction він зберігається повністю. Якщо entry file містить 20,000 токенів, повертається лише його перша чверть, і ви не отримуєте жодної інформації про те, які саме три чверті було втрачено.
Це і є progressive disclosure: невеликий індекс, вартість якого завжди виправдана, а основний обсяг матеріалу розміщено за умовними дверима, які агент відкриває лише за потреби. У Як Claude Code керує своїм вікном контексту наведено решту відомостей про цей розподіл.
Установіть конвертер на VPS із фіксацією версії
Skill — це git-репозиторій. Клонуйте його в каталог skills агента, якого ви використовуєте. Назва каталогу стає slash-командою, тому шлях клонування не є довільним.
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch приймає tag, тому ця команда перемикається на v1.4.0 і не використовує пізніші зміни. Зафіксуйте версію, оскільки skill — це набір інструкцій, яких дотримується агент, а неперевірена зміна цих інструкцій змінює те, що виконується на сервері. GitHub Copilot CLI натомість читає ~/.copilot/skills/, а Amp — ~/.agents/skills/.
Також є однорядкова команда встановлення, npx skills add virgiliojr94/book-to-skill, яка завантажує поточну версію. Використовуйте її для перевірки інструмента. Для всіх повторних запусків використовуйте клон із зафіксованою версією.
Тепер перевірте, які extractors доступні на сервері:
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check показує, які extractors встановлено, і виводить інструкції для встановлення відсутніх компонентів: одну об’єднану команду pip для відсутніх Python-пакетів і підказку для кожного відсутнього системного інструмента. Для цього пакета потрібен Python 3.9 або новіший.
Якщо /book-to-skill не з’являється в автодоповненні після клонування, виконайте /reload-skills або перезапустіть агента. Claude Code відстежує каталоги skills, які існували на момент запуску сесії, тому каталог ~/.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.- Для файлів MOBI і AZW потрібен
ebook-convertіз Calibre. 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, який викликає skill, буде інтерпретатором із потрібними пакетами.
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Зафіксований checkout v1.4.0 оголошує extras 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, але встановлюється default branch проєкту, а не v1.4.0. Крім того, ви отримуєте лише команду екстрактора, а не skill /book-to-skill. Для встановлення з фіксованою версією використовуйте власний checkout, як описано вище. Проста команда pip install book-to-skill не працює, оскільки станом на October 2026 це ім’я не опубліковане в PyPI.
Не встановлюйте docling, доки він не знадобиться для конкретної книги. Він встановлює стек machine learning, тому перед інсталяцією на невеликому плані перевірте вільне місце на диску.
Запуск для папки документів, зокрема без взаємодії
Команда приймає файл, папку, 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 не розгорнув його до того, як його отримає skill. Якщо передати команді наявний каталог skill, нові джерела буде додано до цього skill, а не створено другий.
Під час інтерактивного запуску команда ставить запитання. Чи є матеріал технічним або переважно текстовим — це визначає extractor. Для чого має допомагати skill — це визначає глибину reference або study і пов’язаний із нею бюджет для кожного розділу. Як назвати skill і, якщо кореневого каталогу skills ще немає або їх кілька, до якого кореневого каталогу його додати. Перед генерацією команда також показує оцінку кількості токенів і часу та очікує підтвердження.
Під час запуску без взаємодії нікому відповідати на ці запитання. Skills, які можна викликати користувачем, працюють у claude -p: додайте slash-команду до рядка prompt, і Claude Code розгорне її до початку запуску. Тому надайте відповіді на запитання в тому самому prompt.
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 у результат. Це оцінка на стороні клієнта, а не сума у вашому рахунку.
Перед тим як будь-яка модель прочитає джерела, процес extraction об’єднує кожне джерело в тимчасовому робочому каталозі під /tmp. На останньому кроці запуску цей каталог видаляється. Якщо джерело не вдається обробити, його пропускають, тому пакетний запуск продовжується. Через це запуск може завершитися успішно, прочитавши менше файлів, ніж ви надали. Порівняйте перелік файлів у фінальному звіті з вмістом папки. Відсутній розділ зазвичай означає відсутнє джерело.
Запускайте процес на сервері, доступ до якого ви готові надати агенту. У матеріалі Безпечний запуск Claude Code на VPS описано питання дозволів.
Куди потрапляє результат, щоб ваш coding agent його знайшов
Згенерований skill потрапляє до кореневого каталогу skills. Важливі два такі каталоги.
~/.claude/skills/<skill-name>/є персональним і доступний у кожному проєкті на цій машині..claude/skills/<skill-name>/розташований у репозиторії та зберігається разом із ним.
У кожному з них є SKILL.md, каталог chapters/ з одним файлом для кожного розділу та допоміжними файлами. Назва каталогу є командою, тому ~/.claude/skills/platform-handbook/ надає вам /platform-handbook, після чого можна вказати тему або звичайне запитання.
Вибирайте кореневий каталог за ліцензією, а не за зручністю. Skill, створений на основі придбаної вами книги, належить зберігати в персональному каталозі. Skill, створений на основі документації, яку написала ваша команда, належить зберігати в репозиторії. У такому разі спільне використання одного skill у кількох репозиторіях стає наступною проблемою, яку потрібно вирішити.
З кожним доданим skill зростає одна з витрат. Опис кожного skill залишається в переліку skills, щоб модель могла вирішити, чи використовувати його. Об’єднаний текст опису обрізається до 1,536 символів для кожного запису, а для всього переліку діє загальний ліміт. Десять skills із книг означають, що десять описів конкурують за цей ліміт. Для skills, які ви завжди викликаєте за назвою, додайте один рядок до згенерованого frontmatter:
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---З disable-model-invocation: true опис повністю виключається з контексту, а skill і далі завантажується повністю, коли ви вводите /platform-handbook. Ви відмовляєтеся від автоматичного пошуку, але отримуєте тихіше контекстне вікно.
Ліцензія MIT поширюється на конвертер, але не на книгу
Це потрібно чітко розуміти, оскільки проблема тут не технічна.
- Ліцензія MIT поширюється на код конвертера та його визначення skill. Вона нічого не говорить про документ, який ви йому передаєте.
- Запуск конвертера для книги, яку ви придбали, на обладнанні під вашим контролем — це створення власних нотаток із вашого примірника.
- Публікація результату є розповсюдженням, а ліцензія MIT на інструмент не надає вам права розповсюджувати матеріали, похідні від чужої книги.
- Результат є похідним твором. Структура та висновки розділів усе одно сформовані під впливом джерела, а похідний твір і далі регулюється авторським правом на джерело.
- skill, створений на основі матеріалів, які не можна розповсюджувати, залишається на машині, де його створили. Не в публічному репозиторії. Не в спільному marketplace команди.
- Публікуйте матеріали, якщо джерело належить вам або має відкриту ліцензію: наприклад, документацію, написану вашою командою, або стандарт, умови якого дозволяють розповсюдження.
Інструмент побудовано з урахуванням цього. Він не містить тексту жодної книги, а видобування даних виконується локально. Закріплений v1.4.0 лише виводить необов’язковий рядок gh skill publish і не запитує про видимість, тому в цьому випадку рішення повністю залишається за вами. Відтоді до гілки за замовчуванням проєкту додали крок публікації, який окремим запитанням з одним словом запитує видимість репозиторію та створює публічний репозиторій лише тоді, коли відповідь є окремим словом public; у всіх інших випадках репозиторій залишається приватним. Вважайте цей крок рішенням щодо ліцензування, оскільки саме ним він і є.
Внутрішні посібники створюють ще одну проблему. У них частіше, ніж прийнято визнавати, містяться облікові дані, а конвертер перетворює 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. Станом на жовтень 2026 року ці дані опубліковано в docs/performance.md проєкту. Ваш показник залежить від використовуваної моделі та її цін.
Проєкт також зазначає, що для відповіді на одне запитання зі skill потрібно у 24–51 разів менше токенів, ніж для відповіді на запитання з усією книжкою, вставленою в контекст. Це показує масштаб економії, а не гарантує конкретний результат, оскільки він залежить від книжки та запитання. Структурний висновок залишається незмінним: конверсія оплачується один раз, а вміст контексту оплачується знову під час кожної розмови, якій потрібна ця книжка.
Навіщо вставляти PDF або створювати індекс RAG?
Вставляння працює і є правильним рішенням для одного запитання щодо одного документа. Але це рішення втрачає перевагу, коли та сама книга потрібна у вівторок, а потім знову в п’ятницю, оскільки щоразу потрібно передавати весь її обсяг.
Пошук, або RAG (retrieval augmented generation), виконується під час обробки запиту й повертає фрагменти, які відповідають вашим словам. Це зручно, коли потрібне точне речення. Але такий підхід слабший, коли корисна інформація є структурою, розподіленою по всьому розділу, оскільки жоден окремий фрагмент не містить її повністю. Skill виконує це вилучення один раз під час конвертації та зберігає структуру, а не фрагменти.
Важливе обмеження: згенерований skill — це стислий виклад із втратами, створений моделлю. Це навчальний допоміжний матеріал, а джерелом залишається оригінал. Якщо точне формулювання має юридичне або протокольне значення, зберігайте PDF і цитуйте безпосередньо з нього. У розділі Порівняння skills із MCP-серверами та файлами правил описано, де доречно застосовувати кожен підхід.
Режими відмови та повідомлення, які ви побачите
Відсканований PDF не дає результату. Екстрактор перевіряє перші сторінки на наявність текстового шару й зупиняється з поясненням, замість того щоб обробляти 400 сторінок із зображеннями. Спочатку виконайте ocrmypdf input.pdf output.pdf, а потім передайте йому вихідний файл.
pip відмовляється встановлювати пакет. error: externally-managed-environment в Ubuntu 24.04 захищає системний Python. Використайте наведене вище віртуальне середовище або встановіть poppler-utils і повністю відмовтеся від pip.
Розділи визначаються неправильно. Визначення розділів шукає явні заголовки, наприклад Chapter 7, а також їхні мовні варіанти. Воно також розпізнає римські цифри, наприклад Chapter IV або IV. Title. Якщо в книзі використовуються звичайні ненумеровані заголовки розділів, поділ буде неправильним. У такому разі вкажіть під час запуску, де починаються розділи, замість того щоб покладатися на автоматичне визначення.
Команда не існує. Якщо /book-to-skill немає в автодоповненні, це означає, що каталог skills було створено після початку вашої сесії. Виконайте /reload-skills або перезапустіть agent.
Docling працює надто довго. За швидкості приблизно 1.5 секунди на сторінку обробка великої книги займає кілька хвилин процесорного часу. На спільному сервері цей процес також конкурує за ресурси з іншими розміщеними вами сервісами. Коли запуск запитує про тип вмісту, вкажіть "text-heavy" або самостійно передайте --mode text під час виконання scripts/extract.py. --mode technical — це відповідь, яка вибирає docling.
Джерело непомітно зникає. Файл, який неможливо прочитати, пропускається, щоб пакетна обробка могла завершитися. Після цього запуск повідомляє про успіх для меншої кількості джерел, ніж ви передали. Єдине місце, де це видно, — список файлів у підсумковому звіті. Звичка порівнювати завершений запуск із фактично переданими йому даними корисна далеко за межами цього інструмента. Метод Depth Tree у навичці unlazy допомагає змусити agent дотримуватися такого самого стандарту, а не оголошувати завдання виконаним достроково.
Застосуйте той самий підхід вручну
Інструмент лише спрощує роботу. Переносною частиною є структура, а текстовий редактор дає змогу створити її для будь-яких довідкових матеріалів, якими ви володієте.
- Створіть один вступний файл і тримайте його обсяг близько 4,000 токенів, на які орієнтується конвертер. Додайте до нього названі поняття з їхніми точними формулюваннями, а також індекс із переліком усіх файлів із деталями та тем, які містить кожен файл.
- Розділіть матеріал на файли обсягом приблизно 1,000 токенів, по одній темі в кожному. Називайте файли так, щоб із самої назви було зрозуміло, що в них міститься.
- Опишіть кожен із цих файлів у вступному файлі в реченні, де зазначено, коли його потрібно читати.
Крок 3 найчастіше пропускають, хоча саме він забезпечує роботу цього підходу. Агент визначає, який файл відкрити, читаючи індекс. Тому файл, якого немає в описі індексу, агент ніколи не відкриє. Індекс є продуктом, а файли розділів — сховищем.
Якщо вступний файл не перевищує бюджет ущільнення, уся структура зберігається протягом тривалого сеансу. Це правило діє незалежно від того, створив файли конвертер чи ви зробили це вручну.
FAQ
Чи можна опублікувати skill, створений на основі придбаної книги?
Ні, якщо тільки ліцензія цієї книги не дозволяє розповсюдження. Ліцензія MIT для конвертера поширюється на код конвертера, але не на матеріали, які ви йому передаєте, а згенерований skill є похідною роботою на основі книги. Зберігайте його в ~/.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, активуйте його, встановіть туди екстрактори, а потім запустіть агента з цієї самої оболонки. Skill викликає python3, тому використовує інтерпретатор, який знаходить у PATH. Тепер це інтерпретатор із віртуального середовища.
Чому мій згенерований skill не відображається як slash command?
Є дві причини. Назва команди походить із назви каталогу, тому skill має розташовуватися в ~/.claude/skills/<name>/SKILL.md або .claude/skills/<name>/SKILL.md, а SKILL.md має бути написано саме так. Якщо шлях правильний, виконайте /reload-skills або перезапустіть агента. Claude Code підхоплює зміни в каталогах skill, за якими він уже стежить, але каталог skills, створений після початку сеансу, до цього моменту взагалі не відстежується.