mirror of
https://github.com/virgiliojr94/book-to-skill.git
synced 2026-09-14 19:43:03 +08:00
Anton Novoselov
349dc4365b
* feat(skill): default generated skills to ~/.agents/skills with Claude Code symlink Personal (user-level) installs of generated book skills now land in the cross-agent root ~/.agents/skills/<slug>/ for every host, so one copy serves Copilot CLI, Amp, and Claude Code. Claude Code does not scan that root, so Step 10 creates a symlink at ~/.claude/skills/<slug> pointing to the generated skill. Host-private and project-local destinations stay available on explicit request, and a pre-existing real directory at ~/.claude/skills/<slug> triggers a migration offer instead of a silent replace. * fix(skill): guard the Claude Code symlink and scope discovery claims Skip symlink creation when a real directory remains at ~/.claude/skills/<skill_name> (ln -sfn would nest the link inside it and Claude Code would keep loading the stale copy), report discovery only for the destination actually used, use <skill_name> consistently for the skill folder placeholder, and clarify in README and how-it-works that the symlink is created when running under Claude Code. * docs: state the Claude Code symlink as attempted-and-verified, not a fact Align README and the how-it-works pipeline diagram with Step 10's read-back rule: the symlink is attempted and verified, and the run report states the actual result. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skill): keep Hermes Agent on its own personal root under the new default Hermes Agent landed after this branch was opened. Its personal root is partitioned by category ($HERMES_HOME/skills/<category>) and it does not scan the cross-agent root, so it is the one host the collapse cannot serve from ~/.agents/skills. Carry it forward rather than regress it: the Step 5 table keeps the Hermes row, a personal Hermes install uses that root and takes no symlink, and the "Discoverable by" line names Hermes alone for it - no cross-agent claim, since no other host scans the Hermes root. The intro sentence no longer says one copy serves every host, because with Hermes carved out that is not true. README and the pipeline diagram say the same. * fix(skill): name the relocation target as the final skill directory `mv <src> <dest>` was grammatical under both readings and only one worked. With <dest> read as a root, the printed line breaks the symlink the run had just created: the skill lands at <root>/<skill_name> while `ln -sfn <root>` points one level up, so Claude Code resolves to a directory with no SKILL.md. The placeholder is now <dest_root>/<skill_name>, so the move target names the final skill directory and there is one reading left. The fill rule says so explicitly, shows the broken form, and requires the resolved paths be substituted rather than the placeholders printed. --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
3.8 KiB
3.8 KiB
description, seo_title
| description | seo_title |
|---|---|
| The full book-to-skill walkthrough, Steps 0-10: document extraction, chapter detection, framework mining, depth budgets, and how the agent skill gets assembled. | How book-to-skill Works - Book to Agent Skill, Step by Step |
⚙️ How it works
One file · a folder · a glob · a list of paths
│
▼
Step 1.5 — "Technical or text-heavy book?"
│
├── technical → Docling (tables + code blocks as markdown, ~1.5s/page)
└── text → pdftotext → pypdf → pdfminer (instant)
│
▼
scripts/extract.py <paths…> --mode <technical|text>
per source: PDF → pdftotext/Docling · EPUB → ebooklib → stdlib zipfile · DOCX/HTML/RTF/…
(one bad source is skipped with a warning; the rest still process)
│
├── /tmp/book_skill_work/full_text.txt (all sources merged, with source markers)
└── /tmp/book_skill_work/metadata.json (aggregated stats + per-source array)
│
▼
Claude analyzes structure
(title, author, chapters, ToC — spanning all sources)
── or, if targeting an existing skill: folds new content in (Mode 4)
│
▼
Generates per-chapter summaries (800–1,200 tokens each)
technical → includes Code Examples + Reference Tables sections
Generates glossary, patterns, cheatsheet
Generates master SKILL.md with core mental models
│
▼
Skill written to:
~/.agents/skills/<slug>/ (cross-agent: Copilot CLI, Amp, Codex)
~/.claude/skills/<slug>/ (symlink → above, attempted under
Claude Code and verified by
read-back; report states the result)
$HERMES_HOME/skills/<category>/<slug>/
(Hermes Agent: its own personal root,
not the cross-agent one, no symlink)
/tmp/book_skill_work/ 🗑️ cleaned up
Extraction benchmark (103-page technical book, CPU only):
| Method | Time | Tokens | Tables | Code blocks |
|---|---|---|---|---|
| pdftotext | 0.1s | 27K | 0 | 0 |
| Docling | 164s | 27K (+1.2%) | 48 | 36 |
Real conversions (measured: pages, extracted tokens, chapters auto-detected, estimated one-pass cost on Claude Sonnet 4.5 at $3/$15 per MTok):
| Book | Format | Pages | Tokens | Chapters | ~Cost |
|---|---|---|---|---|---|
| Think Python 2 | 244 | 119K | 19 | $0.88 | |
| Working Backwards | 371 | 175K | 10 | $0.96 | |
| Pro Git | 501 | 229K | — † | $1.23 | |
| Moby-Dick | EPUB | — | 301K | — † | $1.42 |
† Chapter auto-detection needs explicit Chapter N / Capítulo N headings. Pro Git
uses section titles and Moby-Dick uses chapter titles / roman numerals, so neither
auto-segments — extraction and conversion still work, but you point at sections
manually. A full skill costs roughly $1 per book; far less than re-reading the
PDF every session.
Design principles (click to expand)
- Density over completeness — a 1,000-token summary beats a 10,000-token excerpt
- Practitioner voice — "Use X when Y", not "The book explains X"
- Front-loaded SKILL.md — compaction keeps the first ~5,000 tokens; the most important content comes first
- On-demand chapters — the topic index tells Claude which file to read; chapters load only when needed
- Never raw text — always synthesize, summarize, extract signal from the source