virgiliojr94/book-to-skill

📚 book‑to‑skill – turn any technical book (or similar document collection) into an Agent Skill that your AI‑assistant can query on‑demand.

What it does

• Input: a PDF, EPUB, DOCX, MD, HTML, RTF, MOBI, a folder or a glob of such files.
• Output: a directory that follows the open Agent Skills standard (SKILL.md plus per‑chapter markdown files, glossary, patterns, cheatsheet, etc.).
• The generated skill lives in the host’s skill folder (~/.copilot/skills/…, ~/.agents/skills/…, ~/.claude/skills/…).
• When an LLM‑agent (GitHub Copilot CLI, Amp, Claude Code) receives a command like /my‑book replication, it loads only the relevant chapter file, so the query uses 24‑51× fewer tokens than dumping the whole book into the prompt.

Why it matters

• Reading a book once and forgetting details is common; searching PDFs only returns page numbers, and asking an LLM often leads to hallucinations.
• By distilling the book into structured knowledge (frameworks, decision rules, anti‑patterns, indexed chapters), the skill gives the agent exact, on‑demand access to the original content without re‑scanning the whole file each time.
• Works with any host that supports the Agent Skills spec, making the skill portable across Copilot CLI, Amp, Claude Code, etc.

What it generates (example layout)

File	Role	Approx. size
SKILL.md	Core mental models + chapter index	~4 k tokens
chapters/ch01‑*.md …	One markdown per chapter, loaded only when asked	~1 k tokens each
glossary.md	Alphabetical list of key terms with chapter references	~1.5 k tokens
patterns.md	Collected techniques, algorithms, design patterns	~2 k tokens
cheatsheet.md	Decision tables / quick‑reference rules	~1 k tokens

How it works (high‑level)

1. Extractor (Python): Detects file type, picks the appropriate tool (e.g., pdftotext, docling, ebooklib, python‑docx, etc.) and converts each source to clean text + minimal metadata.
2. Analyzer: Splits the text into chapters, extracts headings, identifies key terms, patterns, and decision rules.
3. Generator: Follows a spec‑driven template to emit the SKILL.md bundle described above. Chapter files are kept separate so the agent loads only what is needed.
4. Optional post‑process: Validate the skill against host‑specific rules (tools/validate_skill.py) and publish it to a private GitHub repo for easy sharing.

Installation & quick start

# Install the converter as a cross‑agent skill (one‑liner)
npx skills add virgiliojr94/book-to-skill

# Or clone manually into the host’s skill directory
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

Then run the command (the tool registers /book-to-skill as a CLI entry):

/book-to-skill ./my‑book.pdf            # create a skill named from the file
/book-to-skill ./docs/ --skill docs‑kit # convert a whole folder

The resulting skill can be used immediately:

/my‑book replication   # asks the agent to answer using the appropriate chapter

Typical use cases beyond books

• Internal documentation (runbooks, ADRs, onboarding guides) → a single skill you can query while coding.
• Brand / design systems → turn a style guide into a searchable skill for copy‑writers.
• Research collections → merge papers and personal notes into one up‑datable skill.
• Specs & standards → query RFCs or API contracts without opening the PDF each time.

Privacy & licensing

• All extraction runs locally; no files are uploaded.
• The tool ships under the MIT license. The generated skill is considered your personal notes – you must not redistribute copyrighted content.

---

TL;DR: book‑to‑skill is a Python‑based converter that transforms any technical book or structured document collection into a compact, standards‑compliant Agent Skill, enabling LLM‑powered assistants to answer questions from the original material with dramatically lower token usage and no hallucination.