book-to-skill

How to use it

Install via the cross-agent skills CLI, or clone into a skills folder:

npx skills add virgiliojr94/book-to-skill

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

Run with /book-to-skill <path|folder|glob> [skill-name]; modes include analyze-only, generate-from-analysis, and update/fold-in (merge new material into an existing skill). After conversion it can publish the skill to GitHub (private by default) so other hosts install it with npx skills add. Check extractor availability without a file via python3 scripts/extract.py --check.

Install destinations differ by host, and this is the detail the summary flattens: the skill lands in ~/.agents/skills/<slug>/ (discovered natively by Copilot CLI, Amp, Codex, and OpenClaw under default state). Under Claude Code it also attempts a verified symlink at ~/.claude/skills/<slug>/, reporting failure if the read-back doesn't confirm. Hermes Agent does not scan the cross-agent root — it installs to $HERMES_HOME/skills/<category>/<slug>/. A non-default OPENCLAW_STATE_DIR also breaks cross-agent discovery.

How it works

Deterministic Python extractor → clean text, then a spec-driven generator (the agent follows SKILL.md) produces the structured skill. The extractor tries format tools in order and uses the first installed; plain text, Markdown, reStructuredText, and AsciiDoc need no extra deps. For PDFs it asks whether the book is technical or prose-heavy and picks accordingly: Docling preserves tables and code blocks, pdftotext is faster for prose. Two tooling scripts are worth noting for adopters: tools/discovery_tax.py measures token cost against a context-dump baseline, and tools/validate_skill.py --lens claude|copilot|amp checks a generated SKILL.md against per-host rules.

Limits

• Scanned PDFs fail fast. A page-image PDF with no text layer has nothing to extract; the tool checks the first pages and stops with an explanation rather than producing an empty skill. Run ocrmypdf input.pdf output.pdf first.
• Copyright/redistribution. The output is a synthesized derivative that (per its Quality Rule #7) never copies raw passages, but the project explicitly warns against publishing or sharing skills of copyrighted works — keep those private. MIT covers the converter code only, not any document you process.
• Processing is local (files aren't uploaded by the tool), but if your agent's model is cloud-hosted, fed text follows that provider's terms like any prompt.

The 24×–51× token-reduction claim is stated as measured on real books; per-book tables and methodology live in docs/performance.md, not on this page — verify there before citing the number.