Biến sách kỹ thuật thành agent skill cho coding agent

Biến sách kỹ thuật thành agent skill: bạn nhận được gì

Để biến một sách kỹ thuật thành agent skill, bạn cung cấp cho một công cụ chuyển đổi file PDF, EPUB, bản xuất DOCX hoặc thư mục chứa các tài liệu nội bộ mà bạn đã sở hữu. Công cụ này tạo một thư mục skill: một file entry chứa các framework đã đặt tên cùng với mục lục các chương, và một file cho mỗi chương. Agent chỉ đọc file chương khi câu hỏi của bạn yêu cầu. Toàn bộ nội dung sách không được đưa vào context window. Chỉ mục lục được đưa vào.

Đây là công việc ngược với viết agent skill từ đầu, trong đó bạn mã hóa một quy trình mà mình đã biết. Ở đây, kiến thức đã tồn tại nhưng không ai truy cập được: một file PDF 800 trang của nhà cung cấp, hoặc một sổ tay chưa được mở từ khi người viết nó rời đi. Công việc chính là nén và lập chỉ mục. Nếu bạn chưa biết skill là gì, hãy đọc agent skill thực sự là gì trước.

Công cụ chuyển đổi được dùng ở đây là book-to-skill, một skill có giấy phép MIT chạy trên chính máy của bạn. Tag hiện tại vào tháng 8 năm 2026 là v1.4.0. Cấu trúc mà công cụ tạo ra quan trọng hơn bản thân công cụ. Phần cuối cùng trước FAQ sẽ hướng dẫn cách tự tạo cấu trúc này.

Vì sao ngân sách token quyết định toàn bộ thiết kế

Một cuốn sách được đưa vào context window sẽ tiêu tốn toàn bộ kích thước của nó trong mỗi cuộc hội thoại cần đến. Một skill chỉ tốn entry file một lần, cộng thêm những chapter mà câu hỏi thực sự cần. Project đặt ngân sách cho từng file mà nó tạo ra.

[
  {
    "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, được giới hạn ở 4,000 token và chứa các framework có tên cùng chỉ mục chapter. Mỗi chapter file có khoảng 1,000 token và nằm trên disk cho đến khi có yêu cầu đọc nó. Các supporting file cũng tương tự: 1,500 token cho glossary.md, 2,000 cho patterns.md, 1,000 cho cheatsheet.md.

Các ngân sách này phù hợp với cách Claude Code thực sự sử dụng context. description của skill nằm trong danh sách skill để model biết skill đó tồn tại. Phần nội dung được load khi skill được invoke, và sau khi load sẽ tiếp tục nằm trong context cho đến hết session. Vì vậy, mỗi dòng trong entry file đều là chi phí lặp lại. Supporting file chỉ được load khi agent đọc chúng, nhờ đó các file theo từng chapter có chi phí thấp.

Có một giới hạn chặt hơn đứng sau con số của entry file. Khi auto-compaction tóm tắt một cuộc hội thoại dài, Claude Code sẽ gắn lại lần invoke gần đây nhất của từng skill sau phần tóm tắt và giữ 5,000 token đầu tiên của mỗi skill, trong tổng ngân sách 25,000 token cho tất cả skill được gắn lại. Entry file nằm trong 5,000 token sẽ được giữ nguyên sau khi compaction. Entry file dài 20,000 token sẽ chỉ quay lại với một phần tư đầu tiên, và không có thông tin nào cho biết ba phần tư còn lại đã bị thiếu.

Đó là progressive disclosure: một chỉ mục nhỏ luôn đáng với chi phí của nó, còn phần lớn nội dung nằm sau một cánh cửa mà agent chỉ mở khi cần. Cách Claude Code quản lý context window trình bày phần còn lại của cơ chế tính này.

Cài converter trên VPS và cố định theo một bản release

Skill này là một git repository. Hãy clone nó vào thư mục skills của agent bạn sử dụng. Tên thư mục sẽ trở thành slash command, nên đường dẫn clone không phải lựa chọn tùy ý.

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

--branch nhận một tag, nên lệnh này checkout v1.4.0 và không lấy các thay đổi về sau. Hãy cố định phiên bản này, vì skill là tập hợp các chỉ dẫn mà agent thực hiện, và một thay đổi chưa được review trong các chỉ dẫn đó cũng là thay đổi đối với những gì chạy trên server của bạn. GitHub Copilot CLI đọc ~/.copilot/skills/, còn Amp đọc ~/.agents/skills/.

Ngoài ra còn có lệnh cài đặt một dòng, npx skills add virgiliojr94/book-to-skill, lệnh này fetch phiên bản hiện tại. Dùng nó để thử tool. Với mọi lần chạy lại, hãy dùng bản clone đã cố định phiên bản.

Bây giờ xác nhận các extractor hiện có trên máy:

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

--check báo cáo các extractor đã được cài đặt và in lệnh cài đặt cho từng extractor còn thiếu. Package này cần Python 3.9 trở lên.

Nếu /book-to-skill không xuất hiện trong autocomplete sau khi clone, hãy khởi động lại agent. Claude Code theo dõi các thư mục skill đã tồn tại khi session bắt đầu, nên ~/.claude/skills/ bạn tạo cách đây hai phút vẫn chưa được theo dõi.

Bạn thực sự cần những extractor nào?

Không cần cài gì ngoài Python, vì mọi định dạng đều có phương án fallback từ standard library. Các phương án fallback kém hơn. Trên server nhỏ, thời gian bị lãng phí là thời gian cài những extractor bạn không dùng.

• pdftotext, thuộc package poppler-utils, xử lý các PDF nhiều văn bản và gần như chạy tức thì. Cài bằng sudo apt install poppler-utils.
• pypdf và pdfminer.six là các phương án fallback bằng Python cho PDF.
• docling dùng cho các PDF kỹ thuật có giá trị nằm trong bảng và đoạn code. Dự án đo được thời gian xử lý khoảng 1.5 giây mỗi trang.
• ebooklib cùng beautifulsoup4 đọc EPUB đúng cách. Nếu không có chúng, tool sẽ fallback sang reader zipfile của standard library.
• python-docx đọc DOCX và striprtf đọc RTF.
• ebook-convert của Calibre là bắt buộc với file MOBI và AZW.
• ocrmypdf chạy OCR (nhận dạng ký tự quang học) trên sách scan hoàn toàn không có text layer.

Trên Ubuntu 24.04, lệnh pip3 install pypdf thuần sẽ dừng với lỗi sau:

error: externally-managed-environment

Đây không phải lỗi pip. Ubuntu và Debian đánh dấu Python hệ thống là do apt quản lý, nên pip từ chối ghi vào đó. Có 2 cách xử lý. sudo apt install poppler-utils cài một binary và không cần pip, còn pdftotext tự xử lý được phần lớn PDF văn bản. Với các Python extractor, hãy tạo virtual environment rồi khởi động agent bên trong environment đó. Khi đó python3 mà skill gọi sẽ là interpreter chứa các package cần thiết.

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 khai báo các extra pdf, epub, docx, rtf, technical và all, trong đó technical là docling. Trang hướng dẫn cài đặt của dự án cũng hiển thị pip install "book-to-skill[pdf,epub,docx]", nhưng tên đó chưa được publish trên PyPI tính đến tháng 8 năm 2026. Vì vậy, hãy cài từ checkout của bạn như trên.

Chưa cần cài docling cho đến khi có sách cần nó. Package này kéo theo một machine learning stack, nên hãy kiểm tra dung lượng đĩa còn trống trên plan nhỏ trước khi cài.

Chạy trên một thư mục tài liệu, kể cả ở chế độ headless

Lệnh nhận một file, một thư mục, một glob được đặt trong dấu ngoặc kép hoặc nhiều path cùng lúc, sau đó là tên skill tùy chọn. Bạn có thể cung cấp mọi loại nội dung đặt trong một thư mục, kể cả một bộ RFC (request for comments, các tài liệu định nghĩa giao thức 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

Đặt glob trong dấu ngoặc kép để shell không expand nó trước khi skill nhận được. Nếu trỏ lệnh vào một thư mục skill đã có, các nguồn mới sẽ được gộp vào skill đó thay vì tạo skill thứ hai.

Lần chạy tương tác sẽ đặt câu hỏi. Tài liệu là tài liệu kỹ thuật hay thiên về văn bản, từ đó quyết định extractor. Bạn muốn độ sâu tham chiếu hay độ sâu học tập, từ đó quyết định budget cho từng chương. Skill sẽ có tên gì và đặt trong skills root nào. Lệnh cũng in ra ước tính token và thời gian trước khi tạo, rồi chờ bạn xác nhận.

Lần chạy headless không có người trả lời các câu hỏi đó. Các skill có thể được gọi từ người dùng vẫn hoạt động trong claude -p: đặt slash command vào chuỗi prompt, Claude Code sẽ expand nó trước khi lần chạy bắt đầu. Vì vậy, hãy trả lời các câu hỏi ngay trong cùng 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 tự động phê duyệt các tool mà lần chạy cần, vì permission prompt khi không có terminal để trả lời sẽ khiến lần chạy không bao giờ hoàn tất. Thêm --output-format json sẽ đưa total_cost_usd vào kết quả; đây là ước tính ở phía client, không phải chi phí bạn bị tính.

Quá trình extraction hợp nhất mọi nguồn vào một work directory tạm thời bên dưới /tmp trước khi model đọc chúng. Bước cuối của lần chạy sẽ xóa directory đó. Nguồn nào extraction thất bại sẽ bị bỏ qua để batch vẫn tiếp tục. Vì vậy, lần chạy có thể báo thành công dù đã đọc ít file hơn số file bạn cung cấp. Hãy đối chiếu inventory file trong báo cáo cuối với nội dung thực tế trong thư mục. Nếu thiếu một chương, nguyên nhân thường là thiếu source.

Hãy cung cấp cho lần chạy một server mà bạn sẵn sàng giao cho agent. Chạy Claude Code an toàn trên VPS trình bày phần quyền truy cập.

Vị trí lưu output để coding agent tìm thấy

Skill được tạo sẽ nằm trong thư mục gốc của các skill. Có 2 thư mục cần chú ý.

• ~/.claude/skills/<skill-name>/ là thư mục cá nhân và có sẵn trong mọi project trên máy đó.
• .claude/skills/<skill-name>/ nằm bên trong một repository và đi cùng repository đó.

Trong mỗi thư mục, bạn sẽ có SKILL.md, một thư mục chapters/ chứa mỗi chapter một file, cùng các file hỗ trợ. Tên thư mục là command, nên ~/.claude/skills/platform-handbook/ sẽ cung cấp /platform-handbook. Sau đó, bạn có thể truyền vào một topic hoặc một câu hỏi thông thường.

Hãy chọn thư mục gốc dựa trên quyền sử dụng, không dựa trên sự tiện lợi. Skill được tạo từ một cuốn sách bạn đã mua thuộc thư mục cá nhân. Skill được tạo từ tài liệu do team của bạn viết thuộc repository. Khi đó, chia sẻ một skill giữa nhiều repository là vấn đề tiếp theo cần giải quyết.

Một chi phí tăng theo số lượng skill bạn thêm. Mô tả của mỗi skill vẫn nằm trong danh sách skill để model quyết định có sử dụng skill đó hay không. Phần văn bản mô tả kết hợp bị cắt ở 1,536 ký tự cho mỗi entry, và toàn bộ danh sách cũng có giới hạn. Mười skill từ sách nghĩa là có mười phần mô tả cùng cạnh tranh trong giới hạn đó. Với những skill bạn luôn gọi bằng tên, hãy thêm một dòng vào frontmatter được tạo:

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

Với disable-model-invocation: true, phần mô tả hoàn toàn không chiếm context, trong khi skill vẫn được load đầy đủ khi bạn nhập /platform-handbook. Bạn mất khả năng tự động discovery, nhưng context window sẽ ít nhiễu hơn.

Cấp phép: MIT áp dụng cho converter, không áp dụng cho sách

Hãy chính xác về điểm này, vì lỗi ở đây không phải lỗi kỹ thuật.

• Giấy phép MIT áp dụng cho mã của converter và định nghĩa skill của nó. Giấy phép này không nói gì về tài liệu bạn đưa vào.
• Chạy converter trên một cuốn sách bạn đã mua, bằng phần cứng do bạn kiểm soát, tương đương với việc bạn tự ghi chú từ bản sao của mình.
• Công bố kết quả là hành vi phân phối. Giấy phép MIT của công cụ không cấp cho bạn quyền phân phối bất kỳ nội dung nào bắt nguồn từ sách của người khác.
• Output là một tác phẩm phái sinh. Framework và phần tóm lược theo chương vẫn chịu ảnh hưởng của nguồn, nên tác phẩm phái sinh vẫn chịu sự điều chỉnh của bản quyền nguồn.
• Một skill được xây dựng từ tài liệu bạn không được phép phân phối phải nằm trên máy đã tạo ra nó. Không đưa vào repository công khai. Không chia sẻ trên marketplace nội bộ của team.
• Chỉ công bố khi nguồn thuộc về bạn hoặc có giấy phép mở: tài liệu do team của bạn viết hoặc tiêu chuẩn có điều khoản cho phép phân phối lại.

Công cụ được thiết kế theo nguyên tắc này. Công cụ không chứa sẵn nội dung sách, quá trình trích xuất chạy cục bộ, và bước publish hỏi riêng về visibility của repository bằng một câu hỏi chỉ chấp nhận đúng từ public hoặc private, thay vì tự suy đoán. Hãy xem prompt đó là quyết định về cấp phép, vì đúng là như vậy.

Sổ tay nội bộ còn có một vấn đề thứ hai. Chúng thường chứa credential nhiều hơn mọi người thừa nhận, và converter biến một file PDF mà không ai mở thành file mà agent của bạn có thể đọc theo yêu cầu. Hãy đọc một lần các file đã tạo trước khi commit chúng, và xem cách giữ secret bên ngoài AI agent của bạn.

Một lần chuyển đổi tốn bao nhiêu?

Các con số dưới đây là số liệu do chính dự án công bố, không phải số liệu do chúng tôi đo.

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

Trong 4 cuốn sách mà dự án đã đo, mỗi lần chuyển đổi tốn từ 0.88 đến 1.42 đô la Mỹ, trong đó Pro Git tốn 1.23. Các số liệu này được đo trên Claude Sonnet 4.5, với số lượng token lấy từ tiktoken bằng cl100k_base, và được công bố trong docs/performance.md của dự án tính đến tháng 8 năm 2026. Con số thực tế của bạn sẽ thay đổi theo model và mức giá bạn dùng.

Dự án cũng ghi nhận rằng việc trả lời một câu hỏi bằng skill này cần ít hơn 24 đến 51 lần token so với việc dán toàn bộ cuốn sách vào context. Hãy xem đây là quy mô khoản tiết kiệm, không phải một cam kết, vì kết quả phụ thuộc vào cuốn sách và câu hỏi. Dù vậy, điểm chính về cấu trúc vẫn giữ nguyên: chi phí chuyển đổi chỉ phát sinh một lần, còn việc đưa toàn bộ context vào sẽ phát sinh lại trong mỗi cuộc trò chuyện cần đến cuốn sách.

Tại sao không dán PDF hoặc xây dựng một chỉ mục RAG?

Dán nội dung vẫn hiệu quả và là lựa chọn phù hợp khi bạn cần trả lời một câu hỏi về một tài liệu. Cách này không còn phù hợp khi bạn cần cùng một cuốn sách vào thứ Ba rồi lại vào thứ Sáu, vì mỗi lần bạn đều phải trả chi phí cho toàn bộ dung lượng của sách.

Retrieval, hay RAG (retrieval augmented generation), tìm kiếm tại thời điểm truy vấn và trả về các đoạn văn khớp với từ ngữ bạn dùng. Cách này hiệu quả khi bạn cần đúng câu cụ thể. Nó kém hiệu quả khi phần hữu ích là một framework trải dài qua cả chương, vì không có đoạn văn đơn lẻ nào chứa toàn bộ framework đó. Skill thực hiện việc trích xuất một lần trong lúc chuyển đổi và lưu cấu trúc thay vì lưu các đoạn văn.

Giới hạn cần nói rõ: skill được tạo ra là bản tóm tắt có mất mát thông tin do model viết. Đây là công cụ hỗ trợ học tập, còn nguồn gốc vẫn là nguồn gốc. Khi câu chữ chính xác có ý nghĩa pháp lý hoặc mang tính ràng buộc trong protocol, hãy giữ PDF và trích dẫn từ đó. So sánh skill với MCP server và rules file trình bày phạm vi phù hợp của từng cách tiếp cận.

Các trường hợp lỗi và chuỗi bạn sẽ thấy

PDF được quét không tạo ra nội dung nào. Bộ trích xuất kiểm tra các trang đầu để tìm lớp văn bản. Nếu không có, nó dừng và giải thích thay vì xử lý hàng trăm trang ảnh. Trước tiên hãy chạy ocrmypdf input.pdf output.pdf, rồi đưa file đầu ra vào bước tiếp theo.

pip từ chối cài đặt. error: externally-managed-environment trên Ubuntu 24.04 là cơ chế apt bảo vệ Python hệ thống. Hãy dùng virtual environment ở trên, hoặc cài poppler-utils và bỏ qua pip hoàn toàn.

Các chương được tách sai. Cơ chế phát hiện chương tìm các heading rõ ràng như Chapter 7 và các biến thể theo ngôn ngữ. Sách dùng tiêu đề section đơn thuần hoặc số La Mã sẽ bị tách sai. Cách khắc phục là chỉ rõ vị trí bắt đầu của các chương trong lần chạy, thay vì chờ hệ thống tự đoán.

Không tìm thấy command. /book-to-skill không xuất hiện trong autocomplete nghĩa là skills directory được tạo sau khi session của bạn bắt đầu. Hãy khởi động lại agent.

Docling chạy quá lâu. Với tốc độ khoảng 1.5 giây mỗi trang, một cuốn sách dài sẽ mất vài phút CPU. Trên server dùng chung, tiến trình đó còn tranh chấp tài nguyên với mọi dịch vụ khác bạn đang host. Khi lần chạy hỏi về loại nội dung, hãy trả lời "text-heavy", hoặc truyền --mode text khi tự điều khiển scripts/extract.py. --mode technical là câu trả lời để chọn docling.

Một source biến mất mà không có thông báo. File không thể đọc sẽ bị bỏ qua để batch hoàn tất. Sau đó lần chạy vẫn báo thành công, nhưng số source ít hơn số bạn đã cung cấp. Nơi duy nhất thể hiện điều này là file inventory trong báo cáo cuối cùng.

Áp dụng thủ công cùng một mô hình

Công cụ chỉ giúp thao tác thuận tiện hơn. Cấu trúc mới là phần có thể áp dụng lại, và bạn có thể dùng trình soạn thảo văn bản để tạo cấu trúc đó cho mọi tài liệu tham chiếu thuộc quyền sử dụng của mình.

1. Viết một file entry và giữ kích thước của file này gần mức 4,000 token mà converter hướng đến. Đưa các khái niệm đã nêu vào file bằng đúng cách diễn đạt của chúng. Thêm một index liệt kê mọi file chi tiết và các chủ đề mà từng file chứa.
2. Chia tài liệu thành các file, mỗi file khoảng 1,000 token và chỉ chứa một chủ đề. Đặt tên sao cho chỉ cần nhìn filename là biết file chứa nội dung gì.
3. Mô tả từng file đó trong file entry, ngay trong câu nêu thời điểm cần đọc file.

Bước 3 là bước nhiều người bỏ qua, nhưng đây là bước giúp mô hình hoạt động. Agent quyết định mở file nào bằng cách đọc index. Vì vậy, nếu index không mô tả một file thì agent sẽ không bao giờ mở file đó. Index mới là sản phẩm; các file chương chỉ là nơi lưu trữ.

Giữ file entry trong compaction budget để toàn bộ cấu trúc vẫn hoạt động trong một session dài. Quy tắc này áp dụng dù converter tạo các file hay bạn tự tạo chúng.

FAQ

Tôi có thể công khai skill được tạo từ một cuốn sách đã mua không?

Không, trừ khi license của cuốn sách cho phép phân phối lại. MIT license của converter chỉ áp dụng cho code của converter, không áp dụng cho nội dung bạn đưa vào, còn skill được tạo ra là một tác phẩm phái sinh của cuốn sách. Hãy giữ nó trong ~/.claude/skills/ trên máy của bạn. Bạn có thể công khai tài liệu do chính mình viết hoặc các nguồn có license mở. Tool cũng hỏi riêng về khả năng hiển thị của repository và chỉ chấp nhận public hoặc private ở dạng thuần, để quyết định này được thực hiện có chủ ý.

Tôi có cần docling không, hay pdftotext là đủ?

pdftotext từ poppler-utils là đủ cho văn xuôi và chạy gần như tức thì. Hãy cài docling khi giá trị của cuốn sách nằm ở các bảng và đoạn code, vì trình trích xuất văn bản thuần sẽ bỏ qua đúng những phần đó. Đổi lại là tốc độ: project đo được docling mất khoảng 1.5 giây cho mỗi trang, nên một tài liệu 300 trang sẽ tiêu tốn vài phút CPU trên VPS.

Vì sao pip thất bại với externally-managed-environment trên VPS của tôi?

Ubuntu 24.04 và các bản Debian hiện tại đánh dấu Python hệ thống là do apt quản lý. Vì vậy pip từ chối cài đặt vào đó và in ra error: externally-managed-environment. Hãy tạo một virtual environment bằng python3 -m venv ~/.venvs/book-to-skill, kích hoạt nó, cài các extractor trong đó, rồi khởi động agent từ chính shell đó. Skill gọi python3, nên nó sử dụng interpreter hiện có trong PATH. Lúc này đó là interpreter trong virtual environment.

Vì sao skill được tạo không xuất hiện dưới dạng slash command?

Có 2 nguyên nhân. Tên command lấy từ tên thư mục, nên skill phải nằm tại ~/.claude/skills/<name>/SKILL.md hoặc .claude/skills/<name>/SKILL.md, với SKILL.md được viết chính xác như vậy. Nếu path đúng, hãy khởi động lại agent. Claude Code nhận các thay đổi bên trong những thư mục skill mà nó đã theo dõi. Tuy nhiên, thư mục skills được tạo sau khi session bắt đầu thì hoàn toàn chưa được theo dõi.