概要
技術書、ドキュメントフォルダ、ソースコードのコレクションを構造化されたエージェントスキルに蒸留するコマンドラインツール。GitHub Copilot CLI、Amp、Claude Codeと互換性があり、コンテキストに直接入れる場合と比較して、トークン消費量を24〜51倍削減できます。
README プレビュー
\n \n\n\nbook-to-skill\n\n\n Turn any technical book, document folder, or collection of sources into a unified agent skill — ready to study, reference, and use while you work in GitHub Copilot CLI, Amp, or Claude Code.\n\n\n\n \n \n \n \n \n\n\n\n \n\n\n\n 🏆 #10 Python Repository of the Day and #25 Repository of the Day on Trendshift (May 23, 2026)\n\n\n\n Why ·\n What it generates ·\n Beyond books ·\n Usage ·\n Requirements ·\n How it works ·\n Discovery Loop Tax ·\n FAQ ·\n Install ·\n Changelog ·\n Performance ·\n Architecture\n\n\n\n 24×–51× fewer tokens than dumping the book into context to answer one question, measured on real books (how it's measured).\n\n\n**How it works, in 3 steps:**\n\n1. **Point** it at a file, folder, or glob — `/book-to-skill ./my-book.pdf`\n2. **It distills** the book into a skill — frameworks, decision rules, anti-patterns, and per-chapter files. Structure, not a summary.\n3. **Your agent loads it on demand** — ask `/my-book replication` and it reads the right chapter and answers from the real content, no hallucination.\n\n---\n\n## 🤔 Why\n\nYou buy a great technical book. You read it once. Three months later you can't remember chapter 7 existed.\n\nThe usual workarounds don't help:\n- 📄 "Let me just search the PDF" → you get a list of pages, not answers\n- 🧠 "I'll ask the agent about this book" → it either hallucinates or says it doesn't have the content\n- 📝 "I'll take notes as I read" → you end up with a 200-line doc you never open again\n\n**book-to-skill solves this by turning the book into a structured skill your agent loads on demand.**\n\nOnce installed, you just type `/your-book-slug replication` and the agent reads the right chapter and answers from the actual content. No hallucination. No digging through PDFs. The book becomes part of your workflow.\n\nWorks with any host that supports the open [Agent Skills](https://github.com/agentskills/agentskills) standard — GitHub Copilot CLI, Amp, and Clau
FAQ (5)
トラブル対応python-docxがインストールされている場合に、DOCXの表が抽出されたテキストの末尾に移動されてしまう問題を修正するにはどうすればよいですか？
これは、パーサーが最初に document.paragraphs を読み取り、次に document.tables を読み取る場合に発生し、Word 本文内で交錯していた順序が失われます。book-to-skill を DOCX の順序修正を含むリリースにアップグレードしてください。修正されたパーサーは、通常 document.iter_inner_content() を使用して本文ブロックをドキュメント順に反復処理し、Paragraph オブジェクトと Table オブジェクトを出現する順に処理します。順序付きブロック反復処理のない古い python-docx バージョンでは、stdlib ZIP/XML パーサーにフォールバックします。即時の回避策として、仮想環境で pip uninstall python-docx を実行してフォールバックを強制するか、extract_docx_with_zipfile("document.docx") を直接呼び出してください。Chapter 2 の前に出現する表が Chapter 2 見出しよりも前に抽出されることを確認してください。
トラブル対応CIでpytestがbs4とtrafilaturaの5件のテストをスキップと表示する問題を修正するにはどうすればよいですか？
これらのテストは、pytest.importorskip を使用してオプションパッケージを要求しているため、スキップされます。テスト専用の依存関係は、専用の CI ジョブでインストールしてください:
optional-deps:
name: test (optional deps installed)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install pytest beautifulsoup4 trafilatura
- run: pytest tests/ -q既存の依存関係不要のジョブは変更せずそのまま維持してください。ローカルで検証するには:
pip install pytest beautifulsoup4 trafilatura
python3 -m pytest tests/ -q両方のパッケージをインストールすると、結果は 698 passed, 5 skipped から 703 passed, 0 skipped に変わります。影響を受けるテストは、tests/test_html_block_boundaries.py 内の bs4 でゲートされたテストと、tests/test_html_boilerplate_extraction.py 内の4つの trafilatura でゲートされたテストです。
トラブル対応なぜ metadata.json の各ソースで chapter_headings_sample が見つからないのですか？
book_to_skill/utils.py にある CLI のメタデータプロジェクションは chapters_detected と chapters_method をコピーしていましたが、ソースごとの chapter_headings_sample が欠落しており、統合されたトップレベルのサンプルのみがシリアライズされていました。PR #245、コミット b27360ccfc2f92e0a6571dac03e32389a6e4cfe4 を含むビルドにアップグレードしてください：
pip install git+https://github.com/virgiliojr94/book-to-skill.git@b27360ccfc2f92e0a6571dac03e32389a6e4cfe4その後、抽出を再実行します。例：
BOOK_SKILL_WORKDIR="$PWD/repro-output" python3 scripts/extract.py alpha.md beta.md --mode text --install-missing noバージョン 1.4.0 をローカルでパッチする場合は、extract_single_file() の出力を保持している変数を使い、main() 内の各ソースオブジェクトに対して、他のチャプターフィールドの隣に既存の抽出結果を追加します：
"chapter_headings_sample": source.get("chapter_headings_sample", []),サンプルを再計算したり、統合されたトップレベルのサンプルを代入したりしないでください。最初のソースの見出しが後続のソースに関連付けられてしまう可能性があるためです。空のリストと Unicode の見出しは保持する必要があります。pytest -q と ruff check . で検証してください。
トラブル対応OPF manifest の hrefs にフラグメントやパーセントエンコードされたファイル名が含まれている場合に、stdlib の EPUB フォールバックがチャプターを警告なくスキップしてしまう問題を修正するにはどうすればよいですか？
PR fix(epub): resolve encoded manifest hrefs を含むリリースにアップグレードしてください。このバグはコミット f08d343 に存在します。フォールバックにパッチを適用する際は、生の OPF の href をそのまま ZipFile.read() に渡さないでください。まず OPF ディレクトリを基準に解決し、クエリ/フラグメント成分を除去して、パーセントエスケープをデコードしてください:
import posixpath
from urllib.parse import urlsplit, unquote
def manifest_member_name(opf_path, href):
href_path = urlsplit(href).path # drops ?query and #fragment
href_path = unquote(href_path) # Chapter%201.xhtml -> Chapter 1.xhtml
return posixpath.normpath(posixpath.join(posixpath.dirname(opf_path), href_path))その後、zf.read(manifest_member_name(opf_path, href)) を呼び出してください。ElementTree などの XML パーサーは、属性値内の XML エンティティをすでにデコードしています。したがって、chapter.xhtml#section-2 は chapter.xhtml に解決され、OEBPS/content.opf からの Text/Chapter%201.xhtml は OEBPS/Text/Chapter 1.xhtml に解決されます。
トラブル対応Mongolian FVS、Khmer inherent vowels、Shorthand format controls などの不可視の Unicode Default_Ignorable 文字が除去または検出されない問題を修正するにはどうすればよいですか？
book_to_skill/sanitize.py::is_invisible_codepoint() にパッチを適用し、割り当て済みの Default_Ignorable_Code_Point=Yes コードポイントのうち欠落しているものを完全なセットとして含めてください: U+17B4、U+17B5、U+180B、U+180C、U+180D、U+1BCA0、U+1BCA1、U+1BCA2、U+1BCA3。たとえば、それらのスカラー値を共有の不可視コードポイントセットに追加します: 0x17B4, 0x17B5, 0x180B, 0x180C, 0x180D, 0x1BCA0, 0x1BCA1, 0x1BCA2, 0x1BCA3。スキャナー用に別のリストを維持しないでください: tools/scan_generated_skill.py は同じ述語をインポートしているため、それを更新すれば、抽出処理でこれらの文字が除去され、スキャナーでも同じセットが一貫して報告されるようになります。この問題は Python 3.9.5 と Unicode 13.0.0 で検証済みであり、9つのコードポイントはすべてそこですでに割り当てられています。パッチ適用後は、テストスイートを再実行し、影響を受けるスキルを再生成・再スキャンしてください。