Як перетворити технічну книгу на skill агента

Перетворення технічної книги на skill для агента: що ви отримуєте

Щоб перетворити технічну книгу на skill для агента, передайте конвертеру PDF, EPUB, експорт DOCX або каталог внутрішніх документів, якими ви вже володієте. Конвертер створить каталог skill: один основний файл із названими фреймворками та індексом розділів, а також окремий файл для кожного розділу, який агент читатиме лише тоді, коли цього потребує ваше запитання. Книга не потрапляє у вікно контексту. Індекс — потрапляє.

Це протилежне завдання до написання skill для агента з нуля, коли ви кодуєте вже відому процедуру. Тут знання існують, але ніхто не може ними скористатися: PDF виробника на 800 сторінок або посібник, який не відкривали відтоді, як звільнилася людина, що його написала. Це робота зі стиснення та індексації. Якщо термін skill для вас новий, спочатку прочитайте що насправді таке skill для агента.

У цьому матеріалі використовується конвертер book-to-skill — skill із ліцензією MIT, який працює на вашій власній машині. Поточний tag станом на August 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. Вона отримує поточну версію. Використовуйте її, щоб випробувати інструмент. Для всіх повторних запусків використовуйте клон із зафіксованою версією.

Тепер перевірте, які екстрактори доступні на сервері:

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

--check показує, які екстрактори встановлено, і виводить команду встановлення для кожного відсутнього екстрактора. Для пакета потрібен Python 3.9 або новіший.

Якщо /book-to-skill не з’являється в автодоповненні після клонування, перезапустіть агента. 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.
• 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]", але станом на August 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 не розгорнув його до того, як його отримає skill. Якщо вказати наявний каталог skill, нові джерела буде додано до цього skill, а не створено другий.

В інтерактивному режимі команда ставить запитання. Чи є матеріал технічним або переважно текстовим — це визначає extractor. Потрібна глибина довідки чи глибина опрацювання — це визначає бюджет для кожного розділу. Як назвати skill і до якого кореневого каталогу skills його додати. Перед генерацією команда також виводить оцінку кількості токенів і часу та очікує на підтвердження.

У headless-режимі нікому відповідати на ці запитання. 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 команди.
• Публікуйте результат, коли джерело належить вам або поширюється за відкритою ліцензією: наприклад, документацію, написану вашою командою, або стандарт, умови якого дозволяють розповсюдження.

Інструмент побудовано з урахуванням цього. Він не містить вмісту жодної книги, вилучення даних виконується локально, а під час публікації окремо запитується видимість репозиторію. У відповідь приймається лише окреме слово 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. Станом на August 2026 ці дані опубліковано в docs/performance.md проєкту. Ваш показник залежатиме від вибраної моделі та її тарифів.

Проєкт також документує у 24–51 разів меншу кількість токенів для відповіді на одне запитання з skill порівняно з відповіддю на запитання з усієї книжки, вставленої в контекст. Сприймайте це як загальний масштаб економії, а не як гарантований результат, оскільки він залежить від книжки та запитання. Структурний висновок залишається незмінним: за конвертацію платять один раз, а за вставлення всього вмісту в контекст — знову під час кожної розмови, якій потрібна ця книжка.

Навіщо вставляти 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 з боку apt. Використайте наведене вище віртуальне середовище або встановіть poppler-utils і повністю відмовтеся від pip.

Розділи визначаються неправильно. Під час визначення розділів система шукає явні заголовки, наприклад Chapter 7, а також їхні мовні варіанти. Якщо в книзі використовуються звичайні назви секцій або римські цифри, розділення буде неправильним. У такому разі потрібно вказати, де починаються розділи, замість того щоб покладатися на автоматичне визначення.

Команда не існує. Відсутність /book-to-skill в автодоповненні означає, що каталог skills було створено після початку сеансу. Перезапустіть agent.

Docling працює надто довго. За швидкості приблизно 1.5 секунди на сторінку обробка довгої книги займає кілька хвилин процесорного часу. На спільному сервері цей процес також конкурує за ресурси з іншими розміщеними сервісами. Коли система запитує тип вмісту, виберіть "text-heavy" або передайте --mode text, якщо запускаєте scripts/extract.py самостійно. --mode technical — це відповідь, яка вибирає docling.

Джерело непомітно зникає. Файл, який неможливо прочитати, пропускається, щоб пакетна обробка могла завершитися. Після цього запуск повідомляє про успіх для меншої кількості джерел, ніж було передано. Єдине місце, де це видно, — перелік файлів у підсумковому звіті.

Застосуйте той самий підхід вручну

Інструмент лише спрощує роботу. Переносною частиною є структура, а текстовий редактор дає змогу створити її для будь-яких довідкових матеріалів, якими ви володієте.

1. Створіть один вступний файл і тримайте його обсяг близько 4,000 токенів, на які орієнтується конвертер. Додайте до нього названі поняття з їхніми точними формулюваннями, а також індекс із переліком усіх файлів із деталями та тем, які містить кожен файл.
2. Розділіть матеріал на файли обсягом приблизно 1,000 токенів, по одній темі в кожному. Називайте файли так, щоб із самої назви було зрозуміло, що в них міститься.
3. Опишіть кожен із цих файлів у вступному файлі в реченні, де зазначено, коли його потрібно читати.

Крок 3 найчастіше пропускають, хоча саме він забезпечує роботу цього підходу. Агент визначає, який файл відкрити, читаючи індекс. Тому файл, якого немає в описі індексу, агент ніколи не відкриє. Індекс є продуктом, а файли розділів — сховищем.

Якщо вступний файл не перевищує бюджет ущільнення, уся структура зберігається протягом тривалого сеансу. Це правило діє незалежно від того, створив файли конвертер чи ви зробили це вручну.

FAQ

Чи можна публікувати skill, створений на основі придбаної книги?

Ні, якщо лише ліцензія цієї книги не дозволяє повторне розповсюдження. Ліцензія MIT для converter поширюється на код converter, а не на матеріали, які ви йому передаєте, і згенерований skill є похідною роботою книги. Зберігайте його в ~/.claude/skills/ на власній машині. Публікувати можна документацію, яку ви написали самостійно, або матеріали з відкритою ліцензією. Інструмент окремо запитує видимість repository і приймає лише окреме значення 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, активуйте його, встановіть екстрактори в ньому, а потім запустіть свій agent з тієї самої оболонки. Skill викликає python3, тому використовується interpreter, який знаходиться в PATH. Тепер це interpreter із віртуального середовища.

Чому мій згенерований skill не відображається як slash command?

Є дві причини. Назва команди походить від назви каталогу, тому skill має розташовуватися в ~/.claude/skills/<name>/SKILL.md або .claude/skills/<name>/SKILL.md, а SKILL.md має бути написано саме так. Якщо шлях правильний, перезапустіть agent. Claude Code підхоплює зміни в каталогах skill, за якими вже стежить. Але каталог skills, створений після початку сеансу, взагалі не відстежується.