Ubah Buku Teknis Menjadi Skill Agent

Mengubah buku teknis menjadi skill agent: hasil yang diperoleh

Untuk mengubah buku teknis menjadi skill agent, arahkan converter ke PDF, EPUB, ekspor DOCX, atau folder dokumen internal yang sudah Anda miliki. Converter akan membuat direktori skill: satu file entri yang memuat framework bernama beserta indeks bab, dan satu file untuk setiap bab yang hanya dibaca agent ketika pertanyaan Anda memerlukannya. Isi buku tidak pernah dimasukkan ke context window. Indeksnya yang dimasukkan.

Pekerjaan ini berlawanan dengan menulis skill agent dari awal, yaitu saat Anda menyandikan prosedur yang sudah diketahui. Dalam kasus ini, pengetahuan tersebut sudah ada, tetapi tidak dapat diakses siapa pun: PDF vendor setebal 800 halaman, atau handbook yang tidak pernah dibuka sejak penulisnya meninggalkan perusahaan. Pekerjaannya adalah melakukan kompresi dan pengindeksan. Jika istilah skill masih baru bagi Anda, baca terlebih dahulu apa sebenarnya skill agent itu.

Converter yang digunakan di sini adalah book-to-skill, skill berlisensi MIT yang berjalan di mesin Anda sendiri. Tag saat ini per Agustus 2026 adalah v1.4.0. Struktur yang dihasilkannya lebih penting daripada tool itu sendiri, dan bagian terakhir sebelum FAQ menunjukkan cara membuat struktur yang sama secara manual.

Mengapa anggaran token menjadi dasar seluruh desain

Sebuah buku yang ditempelkan ke jendela konteks membebankan seluruh ukurannya pada setiap percakapan yang membutuhkannya. Sebuah skill hanya membebankan file entri satu kali, ditambah bab yang benar-benar terkait dengan pertanyaan. Proyek ini menetapkan anggaran untuk setiap file yang dihasilkannya.

[
  {
    "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"
  }
]

File entri, SKILL.md, dibatasi hingga 4,000 token dan memuat framework yang disebutkan serta indeks bab. Setiap file bab berukuran sekitar 1,000 token dan tetap tersimpan di disk sampai diminta. File pendukung serupa: 1,500 token untuk glossary.md, 2,000 untuk patterns.md, dan 1,000 untuk cheatsheet.md.

Anggaran tersebut sesuai dengan cara Claude Code menggunakan konteks. description sebuah skill berada dalam daftar skill agar model mengetahui bahwa skill tersebut tersedia. Isi skill dimuat saat skill dipanggil. Setelah dimuat, isi tersebut tetap berada dalam konteks selama sisa sesi. Karena itu, setiap baris dalam file entri menjadi biaya yang berulang. File pendukung hanya dimuat saat agen membacanya. Inilah yang membuat file per bab lebih hemat.

Ada batas yang lebih ketat di balik angka file entri tersebut. Saat auto-compaction meringkas percakapan yang panjang, Claude Code melampirkan kembali pemanggilan terbaru setiap skill setelah ringkasan dan mempertahankan 5,000 token pertama dari setiap skill, dalam anggaran gabungan 25,000 token untuk semua skill yang dilampirkan kembali. File entri yang berukuran hingga 5,000 token akan kembali secara utuh setelah compaction. File entri berukuran 20,000 token hanya akan kembali dengan seperempat bagian pertamanya. Tidak ada informasi yang memberi tahu Anda tiga perempat bagian mana yang hilang.

Inilah progressive disclosure: indeks kecil yang selalu sepadan dengan biayanya, sementara sebagian besar materi berada di balik pintu yang dibuka agen secara sengaja. Cara Claude Code mengelola jendela konteks menjelaskan perhitungan lainnya.

Instal converter pada VPS Anda, dengan rilis yang ditetapkan

Skill ini merupakan repositori git. Clone repositori tersebut ke dalam direktori skills milik agent yang Anda gunakan. Nama direktori menjadi slash command, sehingga path clone bukan sekadar pilihan.

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

--branch menerima tag, sehingga perintah ini melakukan checkout v1.4.0 dan tidak mengambil versi setelahnya. Tetapkan versinya, karena skill adalah sekumpulan instruksi yang diikuti agent, dan perubahan yang belum ditinjau pada instruksi tersebut mengubah hal yang dijalankan di server Anda. GitHub Copilot CLI membaca ~/.copilot/skills/, sedangkan Amp membaca ~/.agents/skills/.

Tersedia juga instalasi satu baris, npx skills add virgiliojr94/book-to-skill, yang mengambil versi terbaru saat ini. Gunakan perintah tersebut untuk mencoba tool. Gunakan clone dengan versi yang ditetapkan untuk setiap eksekusi ulang.

Sekarang, pastikan extractor yang tersedia pada server:

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

--check melaporkan extractor yang terinstal dan mencetak perintah instalasi untuk setiap extractor yang belum tersedia. Package ini memerlukan Python 3.9 atau yang lebih baru.

Jika /book-to-skill tidak muncul dalam autocomplete setelah proses clone, restart agent Anda. Claude Code memantau direktori skill yang sudah ada saat sesi dimulai, sehingga ~/.claude/skills/ yang dibuat dua menit lalu belum dipantau.

Ekstraktor apa yang sebenarnya Anda perlukan?

Tidak ada yang wajib selain Python karena setiap format memiliki fallback dari standard library. Fallback tersebut lebih buruk. Pada server kecil, waktu yang terbuang berasal dari instalasi ekstraktor yang tidak Anda perlukan.

• pdftotext, dari paket poppler-utils, menangani PDF yang sebagian besar berisi teks dan hampir langsung selesai. Instal dengan sudo apt install poppler-utils.
• pypdf dan pdfminer.six adalah fallback Python untuk PDF.
• docling ditujukan untuk PDF teknis yang nilai utamanya terdapat pada tabel dan daftar kode. Proyek tersebut mengukur kecepatannya sekitar 1.5 detik per halaman.
• ebooklib bersama beautifulsoup4 membaca EPUB dengan benar. Tanpa keduanya, tool tersebut menggunakan fallback berupa pembaca stdlib zipfile.
• python-docx membaca DOCX dan striprtf membaca RTF.
• ebook-convert milik Calibre diperlukan untuk file MOBI dan AZW.
• ocrmypdf menjalankan OCR (optical character recognition) pada buku hasil pemindaian yang sama sekali tidak memiliki lapisan teks.

Di Ubuntu 24.04, pip3 install pypdf biasa berhenti dengan pesan berikut:

error: externally-managed-environment

Itu bukan berarti pip rusak. Ubuntu dan Debian menandai Python sistem sebagai dikelola oleh apt, sehingga pip menolak menulis ke dalamnya. Ada dua solusi. sudo apt install poppler-utils menginstal binary dan sama sekali tidak memerlukan pip, sedangkan pdftotext secara mandiri mencakup sebagian besar PDF prosa. Untuk ekstraktor Python, buat virtual environment dan jalankan agent dari dalamnya. Dengan demikian, python3 yang dipanggil skill adalah interpreter yang memiliki semua paket tersebut.

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

Repository tersebut mendeklarasikan extras pdf, epub, docx, rtf, technical, dan all. technical adalah docling. Halaman instalasi proyek juga menampilkan pip install "book-to-skill[pdf,epub,docx]", tetapi nama tersebut belum dipublikasikan di PyPI hingga August 2026. Karena itu, lakukan instalasi dari checkout Anda sendiri seperti di atas.

Jangan instal docling sebelum ada buku yang membutuhkannya. Komponen tersebut menarik stack machine learning, jadi periksa ruang disk yang tersedia pada paket server kecil sebelum menginstalnya.

Jalankan pada folder dokumen, termasuk tanpa interaksi

Perintah ini menerima file, folder, glob yang diapit tanda kutip, atau beberapa path sekaligus, lalu diikuti nama skill secara opsional. Anda dapat menggunakan semua jenis konten yang ditempatkan dalam satu direktori, termasuk kumpulan RFC (request for comments, dokumen yang mendefinisikan protokol Internet).

/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

Apit glob dengan tanda kutip agar shell tidak memperluasnya sebelum skill memprosesnya. Jika Anda mengarahkan perintah ke direktori skill yang sudah ada, sumber baru akan digabungkan ke skill tersebut, bukan digunakan untuk membuat skill kedua.

Proses interaktif mengajukan beberapa pertanyaan. Apakah materinya bersifat teknis atau didominasi teks, yang menentukan extractor. Apakah Anda menginginkan kedalaman referensi atau kedalaman pembelajaran, yang menentukan anggaran setiap bab. Apa nama skill tersebut, dan ke dalam skill root mana skill itu harus ditempatkan. Proses ini juga menampilkan perkiraan token dan waktu sebelum pembuatan, lalu menunggu konfirmasi Anda.

Proses tanpa interaksi tidak memiliki pengguna untuk menjawab pertanyaan tersebut. Skill yang dapat dipanggil pengguna berfungsi di claude -p: masukkan perintah slash ke dalam string prompt, lalu Claude Code akan memperluasnya sebelum proses dimulai. Karena itu, jawab semua pertanyaan dalam prompt yang sama.

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 menyetujui terlebih dahulu tools yang diperlukan proses, karena prompt izin tanpa terminal yang terhubung akan membuat proses tidak pernah selesai. Menambahkan --output-format json menyertakan total_cost_usd dalam hasil, yang merupakan perkiraan dari sisi client, bukan biaya yang ditagihkan kepada Anda.

Extraction mengonsolidasikan setiap sumber ke dalam direktori kerja sementara di bawah /tmp sebelum model membaca sumber tersebut, lalu langkah terakhir proses akan menghapus direktori itu. Sumber yang gagal diekstrak akan dilewati agar batch tetap berjalan. Akibatnya, proses dapat melaporkan keberhasilan meskipun file yang dibaca lebih sedikit daripada yang Anda berikan. Bandingkan inventaris file dalam laporan akhir dengan isi folder. Bab yang hilang biasanya disebabkan oleh sumber yang hilang.

Berikan proses tersebut server yang penggunaannya untuk agent sudah Anda setujui. Menjalankan Claude Code dengan aman di VPS membahas aspek izin tersebut.

Ke mana output disimpan agar coding agent Anda dapat menemukannya

Skill yang dihasilkan disimpan di root skills. Ada dua lokasi yang penting.

• ~/.claude/skills/<skill-name>/ bersifat personal dan tersedia di setiap project pada mesin tersebut.
• .claude/skills/<skill-name>/ berada di dalam repository dan ikut berpindah bersama repository.

Di dalam salah satu lokasi tersebut, Anda akan menemukan SKILL.md, direktori chapters/ dengan satu file untuk setiap bab, serta file pendukung. Nama direktori tersebut adalah perintahnya. Jadi, ~/.claude/skills/platform-handbook/ memberi Anda /platform-handbook, dan Anda dapat melanjutkannya dengan topik atau pertanyaan biasa.

Pilih root berdasarkan lisensi, bukan kenyamanan. Skill yang dibuat dari buku yang Anda beli menjadi milik Anda dan harus disimpan di direktori personal. Skill yang dibuat dari dokumentasi yang ditulis oleh tim Anda sendiri harus disimpan di repository. Dengan demikian, berbagi satu skill di beberapa repository menjadi masalah berikutnya yang perlu diselesaikan.

Ada satu biaya yang bertambah setiap kali Anda menambahkan skill. Deskripsi setiap skill tetap berada dalam daftar skill agar model dapat menentukan apakah skill tersebut perlu digunakan. Teks deskripsi gabungan dipotong hingga 1,536 karakter untuk setiap entri, dan keseluruhan daftar juga memiliki batas. Sepuluh skill dari buku berarti ada sepuluh deskripsi yang bersaing untuk menggunakan batas tersebut. Untuk skill yang selalu Anda panggil berdasarkan nama, tambahkan satu baris ke frontmatter yang dihasilkan:

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

Dengan disable-model-invocation: true, deskripsi tetap sepenuhnya berada di luar konteks, dan skill tetap dimuat secara lengkap saat Anda mengetik /platform-handbook. Anda kehilangan discovery otomatis, tetapi context window menjadi lebih ringan.

Lisensi: MIT mencakup converter, bukan bukunya

Pahami hal ini dengan tepat karena kegagalannya bukan masalah teknis.

• Lisensi MIT mencakup kode converter dan definisi skill-nya. Lisensi tersebut tidak mengatur dokumen yang Anda masukkan ke converter.
• Menjalankan converter pada buku yang Anda beli, menggunakan perangkat keras yang Anda kendalikan, berarti membuat catatan dari salinan Anda sendiri.
• Mempublikasikan hasilnya merupakan distribusi, dan lisensi MIT pada tool tidak memberi Anda hak untuk mendistribusikan apa pun yang berasal dari buku milik pihak lain.
• Output tersebut merupakan karya turunan. Kerangka dan rangkuman setiap bab tetap dibentuk oleh sumbernya, dan karya turunan tetap tunduk pada hak cipta sumber.
• Skill yang dibuat dari materi yang tidak boleh Anda distribusikan harus tetap berada di mesin yang membuatnya. Jangan masukkan ke repositori publik atau marketplace tim bersama.
• Publikasikan hanya jika sumbernya milik Anda atau berlisensi terbuka, misalnya dokumentasi yang ditulis tim Anda atau standar yang ketentuannya mengizinkan redistribusi.

Tool ini dirancang berdasarkan prinsip tersebut. Tool ini tidak menyertakan konten buku, proses ekstraksi berjalan secara lokal, dan langkah publish menanyakan visibilitas repositori sebagai pertanyaan terpisah yang hanya menerima kata tunggal public atau private, bukan menentukannya secara otomatis. Perlakukan prompt tersebut sebagai keputusan lisensi karena memang itulah fungsinya.

Buku panduan internal menimbulkan masalah kedua. Dokumen tersebut lebih sering memuat kredensial daripada yang diakui siapa pun, dan converter mengubah PDF yang tidak pernah dibuka menjadi file yang dapat dibaca agent Anda saat diperlukan. Baca file yang dihasilkan satu kali sebelum melakukan commit, lalu lihat menjaga rahasia agar tidak masuk ke AI agent Anda.

Berapa biaya satu konversi?

Angka di bawah ini merupakan hasil pengukuran yang dipublikasikan oleh proyek tersebut, bukan hasil pengukuran kami.

[
  {
    "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
  }
]

Pada 4 buku yang diukur oleh proyek tersebut, satu konversi membutuhkan biaya antara 0.88 dan 1.42 dolar AS, dengan Pro Git sebesar 1.23. Angka tersebut diukur menggunakan Claude Sonnet 4.5, dengan jumlah token dari tiktoken menggunakan cl100k_base, dan dipublikasikan dalam docs/performance.md proyek tersebut per Agustus 2026. Biaya yang Anda dapatkan sendiri akan berubah sesuai model dan harga yang Anda gunakan.

Proyek tersebut juga mendokumentasikan penggunaan token 24 hingga 51 kali lebih sedikit untuk menjawab satu pertanyaan dari skill dibandingkan seluruh buku yang ditempelkan ke context. Anggap angka tersebut sebagai gambaran penghematan, bukan jaminan, karena hasilnya bergantung pada buku dan pertanyaannya. Poin strukturnya tetap sama: biaya konversi dibayar satu kali, sedangkan context dump dibayar lagi pada setiap percakapan yang memerlukan buku tersebut.

Mengapa tidak menempelkan PDF atau membuat indeks RAG?

Menempelkan PDF dapat dilakukan dan merupakan pilihan yang tepat untuk satu pertanyaan tentang satu dokumen. Namun, cara ini tidak lagi tepat ketika buku yang sama diperlukan pada hari Selasa dan kembali diperlukan pada hari Jumat, karena seluruh ukurannya harus diproses setiap kali.

Retrieval, atau RAG (retrieval augmented generation), melakukan pencarian saat kueri diajukan, lalu mengembalikan bagian yang sesuai dengan kata-kata Anda. Cara ini efektif ketika Anda memerlukan kalimat yang tepat. Namun, cara ini kurang efektif ketika informasi yang berguna berupa kerangka yang tersebar di seluruh bab, karena tidak ada satu bagian yang memuatnya secara utuh. Skill melakukan ekstraksi tersebut satu kali saat konversi dan menyimpan strukturnya, bukan bagian-bagian teksnya.

Batasannya perlu dipahami: skill yang dihasilkan adalah ringkasan lossy yang ditulis oleh model. Skill merupakan alat bantu belajar, sedangkan sumber aslinya tetap menjadi rujukan utama. Jika susunan kata yang tepat memiliki konsekuensi hukum atau penting bagi protokol, simpan PDF dan kutip langsung dari sana. Perbandingan skill dengan server MCP dan file rules menjelaskan kapan setiap pendekatan sebaiknya digunakan.

Trykketilstande og de strenge, der vises

En scannet PDF producerer intet. Udpakkeren kontrollerer de første sider for et tekstlag og stopper med en forklaring i stedet for at gennemgå 400 sider med billeder. Kør ocrmypdf input.pdf output.pdf først, og giv derefter outputfilen som input.

pip nægter at installere. error: externally-managed-environment på Ubuntu 24.04 er apt, der beskytter systemets Python. Brug det virtuelle miljø ovenfor, eller installer poppler-utils og spring pip helt over.

Kapitlerne bliver forkerte. Kapitelgenkendelsen leder efter eksplicitte overskrifter som Chapter 7 og sprogvarianter af denne. En bog, der bruger løse sektionsoverskrifter eller romertal, giver en forkert opdeling. Løsningen er at angive, hvor kapitlerne begynder, i stedet for at håbe på, at den gætter rigtigt.

Kommandoen findes ikke. Hvis /book-to-skill mangler i autocomplete, betyder det, at skills-mappen blev oprettet efter starten på din session. Genstart agenten.

Docling tager evigheder. Ved cirka 1,5 sekunder pr. side kræver en lang bog flere minutters CPU-tid. På en delt server konkurrerer denne kørsel med alt andet, du hoster. Svar "text-heavy", når kørslen spørger om indholdstypen, eller angiv --mode text, når du selv kører scripts/extract.py. --mode technical er svaret, der vælger docling.

En kilde forsvinder uden besked. En fil, der ikke kan læses, springes over, så batchkørslen kan afsluttes. Kørslen rapporterer derefter succes for færre kilder, end du angav. Det eneste sted, hvor dette fremgår, er filinventaret i den endelige rapport.

Terapkan pola yang sama secara manual

Tool ini hanya memudahkan pekerjaan. Struktur adalah bagian yang dapat diterapkan kembali, dan editor teks dapat membuatnya untuk materi referensi apa pun yang Anda miliki.

1. Tulis satu file entri dan pertahankan ukurannya mendekati 4,000 token yang menjadi sasaran converter. Masukkan konsep-konsep yang disebutkan dengan rumusan persisnya, serta indeks yang mencantumkan setiap file detail dan topik yang terdapat dalam file tersebut.
2. Bagi materi menjadi file-file yang masing-masing berisi sekitar 1,000 token, dengan satu topik per file. Beri nama file sedemikian rupa sehingga isinya dapat diketahui hanya dari nama file.
3. Jelaskan setiap file tersebut dari file entri, dalam kalimat yang menyatakan kapan file itu harus dibaca.

Langkah 3 adalah langkah yang sering dilewati. Padahal, langkah inilah yang membuat pola tersebut berfungsi. Agent memilih file yang akan dibuka dengan membaca indeks. Jadi, jika suatu file tidak dijelaskan dalam indeks, agent tidak akan pernah membukanya. Indeks adalah produk akhirnya, sedangkan file bab adalah penyimpanan.

Pertahankan file entri di dalam anggaran kompaksi agar seluruh struktur tetap bertahan selama sesi yang panjang. Aturan ini berlaku baik file tersebut dibuat oleh converter maupun oleh Anda.

FAQ

Dapatkah saya menerbitkan skill yang dibuat dari buku yang saya beli?

Tidak, kecuali lisensi buku tersebut mengizinkan redistribusi. Lisensi MIT pada converter hanya mencakup kode converter, bukan materi yang Anda masukkan, dan skill yang dihasilkan merupakan karya turunan dari buku tersebut. Simpan di ~/.claude/skills/ pada mesin Anda sendiri. Anda dapat menerbitkan dokumentasi yang Anda tulis sendiri atau sumber berlisensi terbuka. Tool ini juga menanyakan visibilitas repository sebagai pertanyaan terpisah dan hanya menerima public atau private tanpa tambahan apa pun, sehingga keputusan tersebut tetap dibuat secara sadar.

Apakah saya memerlukan docling, atau cukup menggunakan pdftotext?

pdftotext dari poppler-utils cukup untuk prosa dan hampir seketika selesai. Instal docling jika nilai utama buku terdapat pada tabel dan daftar kode, karena extractor teks biasa menghilangkan bagian-bagian tersebut. Konsekuensinya adalah kecepatan: proyek ini mengukur waktu docling sekitar 1.5 detik per halaman, sehingga manual 300 halaman memerlukan waktu CPU beberapa menit pada VPS.

Mengapa pip gagal dengan externally-managed-environment pada VPS saya?

Ubuntu 24.04 dan Debian saat ini menandai Python sistem sebagai dikelola oleh apt. Karena itu, pip menolak instalasi ke dalamnya dan mencetak error: externally-managed-environment. Buat virtual environment dengan python3 -m venv ~/.venvs/book-to-skill, aktifkan environment tersebut, instal extractor di dalamnya, lalu jalankan agent dari shell yang sama. Skill memanggil python3, sehingga skill menggunakan interpreter yang tersedia pada PATH Anda, yaitu interpreter dari virtual environment tersebut.

Mengapa skill yang saya buat tidak muncul sebagai perintah slash?

Ada 2 penyebab. Nama perintah berasal dari nama direktori. Karena itu, skill harus berada di ~/.claude/skills/<name>/SKILL.md atau .claude/skills/<name>/SKILL.md, dengan SKILL.md dieja persis seperti itu. Jika path sudah benar, restart agent. Claude Code mengambil perubahan di dalam direktori skill yang sudah dipantaunya. Namun, direktori skills yang dibuat setelah sesi dimulai sama sekali belum dipantau.