Skip to content
Maktaba

book-to-skill

virgiliojr94/book-to-skill at e7bb659

1 skill · 24 files shown of 142 · license: MIT · imported 2026-11-10

About

Section titled “About”

book-to-skill is a single agent skill, made by virgiliojr94, that turns a book or other document into a new skill: a SKILL.md core, one file per chapter, a glossary, a patterns file, and a cheatsheet of decision rules. It accepts PDF, EPUB, DOCX, HTML, Markdown, plain text, RTF, and, through Calibre, MOBI and AZW. The work is split between a deterministic Python extractor, which produces clean text and metadata, and the agent, which follows SKILL.md to write the skill. Much of the extractor is defensive: it strips invisible Unicode that can hide prompt injection, detects chapter headings in more than 20 languages, and comes with a scanner for the generated skill and a large regression test suite.

How the repo is organized

Section titled “How the repo is organized”

One skill at the repo root. SKILL.md sits at the top of the repo, so the whole repo is the skill folder. Installing it with npx skills add virgiliojr94/book-to-skill, or with git clone into a skills folder such as ~/.claude/skills/ or ~/.agents/skills/, therefore also copies the tests, docs, and evaluation files, which the skill never uses.

Two halves. The agent follows SKILL.md, a long step-by-step spec (Steps 0 to 11, plus an update workflow) that asks the user a few questions, runs the extractor, and then writes the new skill. The extractor is scripts/extract.py, a thin entry point into the book_to_skill/ package:

  • cli.py and utils.py parse arguments, resolve files, folders, and globs, run each source through its parser, detect chapters, and write the results.
  • parsers/ has one module per format (PDF, EPUB, DOCX, HTML, RTF, plain text, Calibre). Each tries the best installed tool first and falls back to a standard-library method.
  • sanitize.py removes invisible Unicode from all extracted text.
  • dependencies.py offers to install missing optional packages and powers --check.
  • pdf_inspector_integration.py adds an optional fast path for PDFs when the pdf-inspector package is installed.

The extractor writes full_text.txt and metadata.json to a private per-run folder under the system temp directory (or BOOK_SKILL_WORKDIR). The agent writes the generated skill to ~/.agents/skills/<slug>/ by default and, on Claude Code, adds a symlink at ~/.claude/skills/<slug>.

Tools. tools/scan_generated_skill.py is the Step 9.5 safety scan of a generated skill. It imports book_to_skill/sanitize.py, so both layers use the same list of invisible characters. tools/validate_skill.py checks a SKILL.md frontmatter against one host’s rules. SKILL.md does not call it, but CI runs it on the converter’s own SKILL.md.

Dependencies. The extractor needs only the Python standard library. Better extractors are optional: pip extras listed in pyproject.toml (pypdf, pdfminer.six, docling, ebooklib, beautifulsoup4, python-docx, striprtf, trafilatura, pdf-inspector) and the system tools pdftotext and Calibre’s ebook-convert. Calibre is required only for MOBI and AZW. The extractor installs a missing package only when the user agrees or passes --install-missing yes.

Nothing runs automatically. The repo has no plugin manifest, hooks, commands, or agents. The scripts run only when the agent follows SKILL.md and calls them through the shell. The same package can also be pip-installed as a standalone book-to-skill command that only extracts text.

Out of date in the README. The README’s “Repository structure” section shows a scripts/extractor/ folder. The code now lives in book_to_skill/, as docs/architecture.md shows.

Skills

Section titled “Skills”
Skill Summary Files
book-to-skill Makes the agent convert one or more documents into a new agent skill. It asks whether the content is technical or text-heavy, runs the extractor, shows a token estimate, asks the skill’s purpose and name, writes SKILL.md, chapter files, glossary.md, patterns.md, and cheatsheet.md, scans the result, and links it for Claude Code. It is used when the user runs /book-to-skill &lt;path> or asks to turn a document into a skill, and it also has analyze-only and update modes. 20

Repository files

Section titled “Repository files”
File What it does
README.md
LICENSE.md
SECURITY-NOTICE.md Warns that a re-upload of this project at Leutenegger/book-to-skill contains malicious code, and names the official repository and install commands.
tools/validate_skill.py Checks the frontmatter of a SKILL.md against one host’s rules, chosen with --lens (claude, copilot, amp, hermes, openclaw, or opencode; claude by default).

Automated checks

Section titled “Automated checks”

The import scripts ran these checks on every shown file. They look for patterns that deserve a close read, such as hidden characters, wording that tries to override an agent, or commands that download and run code. A flag does not mean a file is malicious, and no flag does not mean it is safe.

Check What it looks for Flagged files
Invisible characters Characters a reader cannot see but a model reads. The page shows each one as ⟦U+…⟧. book_to_skill/utils.py (11), tools/validate_skill.py
Hidden HTML comment A comment that rendered Markdown hides. The page shows it as text. SKILL.md (7)

Other files in the repo

Section titled “Other files in the repo”

These files are listed but not shown. Each name links to the file on GitHub.

Tests

Section titled “Tests”

The pytest suite for the extractor, the parsers, the scanner, the validator, and the evaluation tools, plus a small synthetic PDF and the script that regenerates it. CI runs the suite both with and without the optional extractors installed.

69 files

Benchmarks and evaluation research

Section titled “Benchmarks and evaluation research”

tools/discovery_tax.py estimates how many tokens a whole-book context dump, a PDF-navigating agent, and a generated skill each need to answer one question; docs/performance.md reports its results. docs/research/ holds a plan for testing progressive-disclosure ideas from a research paper, and tools/evals/ and evals/fixtures/ hold the deterministic scripts and synthetic data for it. None of these run during a conversion.

10 files

Documentation website

Section titled “Documentation website”

Source for the MkDocs Material site at booktoskill.is-a.dev: the pages in docs/, the mascot, banner, and logo images, the site configuration, and a template override that sets page titles and share-card tags. The deploy workflow copies README.md and SKILL.md into the site as its Guide and Skill Reference pages.

19 files

Translated READMEs

Section titled “Translated READMEs”

Russian and Simplified Chinese versions of the README.

2 files

Packaging and release

Section titled “Packaging and release”

pyproject.toml makes the extractor pip-installable as the book-to-skill command, with an optional extra for each format, and holds the ruff and pytest settings. CHANGELOG.md is generated from commit messages by git-cliff, using cliff.toml.

3 files

Contributor guides

Section titled “Contributor guides”

Rules for people and coding agents who change the converter: required checks, pull-request conventions, release steps, and a rule to measure before claiming any improvement. CLAUDE.md only points Claude Code to AGENTS.md. None of these files are instructions for converting a book.

3 files

Community, funding, and security policy

Section titled “Community, funding, and security policy”

GitHub issue and pull-request templates, the sponsor list and funding link, and the policy for reporting vulnerabilities privately.

6 files

CI and GitHub settings

Section titled “CI and GitHub settings”

GitHub Actions workflows for tests, lint, security scans, SKILL.md validation, pull-request title and description checks, CodeQL, and the docs deploy, plus Dependabot settings and the git ignore and attributes files.

6 files