book-to-skill

name	book-to-skill
description	Converts books and documents (PDF, EPUB, DOCX, HTML, Markdown, plain text, RTF, MOBI/AZW) into structured agent skills, extracting frameworks, mental models, principles, techniques, and anti-patterns. Use when the user wants to study a document through an agent, apply an author's frameworks while working, or build a reusable knowledge base from a file.
license	MIT
metadata	{"version":"1.0","source":"virgiliojr94/book-to-skill (MIT)","port":"Clean methodology-only port. Upstream blocked by SkillSpector (CRITICAL, 100/100) due to bundled Python extraction scripts (subprocess calls, dynamic imports) and root/privilege references in docs. This port keeps the full prose workflow but replaces the bundled extract.py with the bundle's existing `markitdown` CLI/MCP for text extraction. No scripts, no deps.","relates":"markitdown"}

Book-to-Skill Converter

Transform written knowledge into actionable agent skills by extracting structure — not producing summaries.

Philosophy

Books contain crystallized expertise: frameworks, principles, and techniques that took years to develop. This skill extracts that knowledge into a format an agent can leverage repeatedly.

Extract structure, not summaries. A skill isn't a book report. It's a toolkit of:

• Named frameworks (mental models with clear application)
• Actionable principles (rules that guide decisions)
• Techniques (step-by-step methods)
• Anti-patterns (what to avoid and why)
• Voice calibration (how the author thinks and communicates)

Preserve the author's precision. Frameworks often have specific names for reasons. "The 5 Whys" isn't interchangeable with "ask why multiple times." Capture the exact formulation.

Layer depth appropriately. Simple books → simple skills. Complex books with 10+ frameworks → skills with reference files and on-demand chapters.

---

Modes of Operation

Four paths available. Route based on what the user asks:

1. Full Conversion (Default)

Trigger: User provides one or more document/directory/glob paths without special instructions Action: Run all steps below (Steps 0–9) Output: Complete skill with SKILL.md, chapters/, glossary, patterns, cheatsheet

2. Analyze Only

Trigger: User says "analyze", "just extract", or "I want to review before generating" Action: Run Steps 0–3, then produce a structured extraction report. Stop — do NOT generate skill files. Output: Analysis report for user review

3. Generate from Prior Analysis

Trigger: User has existing analysis notes or previously ran analyze-only Action: Skip Steps 0–3, use the provided analysis as input, run Steps 4–9 Output: Skill files from the provided analysis

4. Update / Fold-in (Existing Skill)

Trigger: User provides new source paths and indicates they want to update an existing skill Action: Run Step 0 (out-of-scope check), Step 1 (validate inputs), Step 1.5 (identify book type), and Step 2 (extract). Then run the Update / Fold-in Workflow to merge the new content into the existing skill files.

---

Skill Locations

When writing the generated book skill, prefer these locations in order:

1. ~/.agents/skills/ (cross-agent personal skills)
2. ~/.copilot/skills/ (Copilot CLI personal skills)
3. ~/.claude/skills/ (Claude Code personal skills)
4. Project-local .agents/skills/ or .claude/skills/

When more than one valid root exists, ask the user once and remember the answer for the session — do not silently default.

---

Step 0 — Out-of-scope check

If no arguments are provided, stop and respond:

"book-to-skill requires a supported document path, folder, or glob pattern. Usage: book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]"

• Identify the input paths and the optional skill slug.
• If the last argument is not a file/folder/glob that exists, and it looks like a skill slug (lowercase hyphens, alphanumeric), treat it as SKILL_NAME.
• Treat all other arguments as INPUT_PATHS.
• If any input path is an existing skill directory (contains SKILL.md and chapters/), or SKILL_NAME matches an existing skill slug, flag as Update/Fold-in (Mode 4).

---

Step 1 — Validate input

Verify at least one supported file, directory, or glob pattern among INPUT_PATHS. Expand directories and globs to find supported files (.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3).

If no supported files are found, stop with a clear error message.

---

Step 1.5 — Identify content type

Before extracting, ask the user:

"What kind of content do these sources have?

1. Technical — has code blocks, tables, formulas, diagrams
2. Text-heavy — mostly prose, few or no tables/code
3. Not sure — I'll use the fast method and warn you if quality seems limited"

Store the answer as BOOK_TYPE (1→technical, 2→text, 3→text).

---

Step 2 — Extract text from the source documents

Use the bundle's markitdown tool to convert each source to Markdown. markitdown handles PDF, EPUB, DOCX, HTML, RTF, and plain text with no OCR needed for text-based files.

# For each input path, convert to Markdown:
markitdown <input-path> -o <tempdir>/book_skill_work/<slug>.md

For .mobi/.azw (Kindle formats), note that markitdown may not handle them directly — ask the user to convert to EPUB first, or extract with a standard tool.

Combine the per-file outputs into <tempdir>/book_skill_work/full_text.txt with clear visually demarcated boundaries between sources.

Also write <tempdir>/book_skill_work/metadata.json recording: combined size, words, pages, token counts, and a detailed list of processed sources.

---

Step 2.5 — Pre-flight cost estimate

Read metadata.json and present the user with an estimate before doing any generation:

📖 Sources detected: <N> source(s)
📄 Combined Pages/Sections: ~<N> | Words: ~<N> | Total tokens: ~<N>K

💰 Estimated token cost (Full Conversion / Update):
   Input  (reading + prompts): ~<N>K tokens
   Output (skill files generated):  ~<N>K tokens
   Total: ~<N>K tokens

   Cost: multiply the token counts by your model's current per-1M-token rates.
   (Prices change often — quote today's rate and label it as an estimate.)

⏱  Estimated time: ~<N> minutes

📁 Files to be generated: SKILL.md + chapter files + glossary + patterns + cheatsheet

➡  Proceed with Full Conversion / Update? (or type "analyze only" to preview first)

How to estimate:

• Input tokens ≈ estimated_tokens from metadata × 1.3 (prompt overhead per chapter pass)
• Output tokens ≈ chapters × per-chapter budget + 4,000 (SKILL.md) + 4,500 (glossary + patterns + cheatsheet)
• Per-chapter budget midpoint by BOOK_TYPE: text ≈ 1,000, technical ≈ 1,800.

Wait for the user to confirm before proceeding. If they say "analyze only", switch to Mode 2.

---

Step 2.6 — REPL-style access for large books (> 50k tokens)

For books over ~50k tokens, treat full_text.txt as a queryable corpus, not a single read. Prefer programmatic probes over unbounded reads:

• Size check before any read
• Find chapter offsets via grep without loading the whole file
• Pull only the chapter you need via line ranges
• Verify a framework is actually mentioned before claiming it in SKILL.md

On books under 50k tokens, a single read is fine.

Why this matters: a 200-page book is ~75k tokens. Re-reading it once per chapter (28 passes) costs ~2M input tokens; pulling only relevant slices keeps generation cost proportional to the output, not the source.

---

Step 3 — Analyze book structure

Read the first ~8,000 characters of full_text.txt to identify:

• Book title and author(s)
• Chapter structure (look for "Chapter N", "PART I", numbered headings, table of contents)
• Core themes and subject domain
• Approximate number of chapters

If mode is "Analyze Only": produce the extraction report now and stop:

## Extraction Report — <Title>
### Author's Core Frameworks
- **<Framework Name>**: <what it is and when to apply>
### Key Principles
- <Principle>: <actionable rule>
### Techniques & Methods
- <Technique>: <step-by-step or how-to>
### Anti-patterns
- <What to avoid>: <why>
### Suggested Skill Name
`{author-lastname}-{core-concept}` — e.g. `cialdini-influence`
### Chapters Detected
| # | Title | Main Frameworks |

---

Step 4 — Ask purpose (Full Conversion only)

Before generating, ask:

"What should this skill help you do? (Pick one or more)

1. Apply the author's frameworks while working
2. Think with the author's mental models
3. Reference specific chapters and concepts
4. All of the above"

Derive DEPTH from the answer:

• Only option 3 → DEPTH=reference — lean, fast-lookup chapters
• Includes 1, 2, or 4 → DEPTH=study — deeper chapters with worked detail

(In Modes 2/3, default DEPTH=study.)

---

Step 5 — Determine skill name

If SKILL_NAME was provided, use it as the skill slug. Otherwise propose two options:

• By author-concept: {author-lastname}-{core-concept} (e.g. cialdini-influence, meadows-systems)
• By title: lowercase hyphens (e.g. designing-data-intensive-apps)

Default to author-concept if the book has a strong methodological identity.

Choose the destination skill root (SKILLS_HOME). Probe the filesystem for existing skill homes and pick by the host the user is running in (Copilot → ~/.agents/skills / ~/.copilot/skills; Claude → ~/.claude/skills).

Selection rules:

1. If exactly one of the host's candidate roots exists, use it without asking.
2. If none exist, ask which root to create — present host-appropriate options.
3. If the user asked for project-local output, prefer the project-local root.
4. If you cannot identify the host, ask.

If $SKILLS_HOME/<skill_name>/ already exists, prompt: Update / Fold-in (Mode 4), Overwrite, or Rename.

---

Step 6 — Create skill directory structure

Create $SKILLS_HOME/<skill_name>/chapters (and the supporting-file directory).

---

Step 7 — Generate chapter summaries

TOKEN BUDGET RULE — CRITICAL (adaptive):

	DEPTH=reference	DEPTH=study
BOOK_TYPE=text	800–1,200 tokens	1,000–1,800 tokens
BOOK_TYPE=technical	1,200–1,800 tokens	2,000–3,000 tokens

• These are per-file targets, not hard caps. Density beats length — never pad.
• Files are loaded on-demand, so a larger chapter only costs tokens when read.
• DEPTH=study is earned with content: reproduce a worked example, expand the "How" of each framework, add a "Why it works / failure mode" note — not by padding.

For EACH chapter/section identified in Step 3:

• Read the corresponding section of full_text.txt.
• Create chapters/ch<NN>-<slug>.md using this structure:

# Chapter N: <Full Title>

## Core Idea
<1–2 sentences>

## Frameworks Introduced
- **<Framework Name>**: <exact formulation — preserve the author's naming>
  - When to use: <specific situation>
  - How: <steps or criteria>

## Key Concepts
- **<Term>**: <precise definition in 1 sentence>

## Mental Models
<2–4 thinking tools: "Use X when Y" or "Think of X as Y">

## Anti-patterns
- **<What to avoid>**: <why it fails>

## Code Examples *(technical books only)*
<  ,  >








 
 
 


 : 
 : 

---

Step 8 — Generate supporting files

glossary.md

• Every significant term, alphabetically sorted
• Format: **Term** — definition (Ch N)
• Max 1,500 tokens

patterns.md

• All concrete techniques, design patterns, algorithms
• Format: ## Pattern Name\n**When to use**: ...\n**How**: ...\n**Trade-offs**: ...
• Max 2,000 tokens

cheatsheet.md

The most differentiated layer — a reasoning aid, not a keyword list. Capture the author's judgment: the decisions they'd make and why.

Prioritize, in order:

1. Decision rules — "When X, do Y, because Z."
2. Decision trees — for choices with more than two branches
3. Trade-off matrices — competing options scored on the dimensions the author cares about
4. Thresholds & defaults — the specific numbers/rules of thumb the author commits to
5. Tells & smells — fast heuristics ("if you see X, you're probably in trouble Y")

Avoid bare term→definition rows (that's the glossary) and prose (that's the chapters). Max 1,200 tokens.

---

Step 9 — Generate the master SKILL.md

CRITICAL TOKEN BUDGET: Keep SKILL.md body under 4,000 tokens. Compaction truncates from the END — put the most important content FIRST.

---
name: <skill_name>
description: "Knowledge base from \"<Full Title>\" by <Author(s)>. Use when applying <author>'s frameworks for <key topics>, studying the book, or referencing its concepts."
---

# <Full Title>
**Author**: <Author(s)> | **Pages**: ~<N> | **Chapters**: <N> | **Generated**: <YYYY-MM-DD>

## How to Use This Skill
- **Without arguments** — load core frameworks for reference
- **With a topic** — find and read the relevant chapter
- **With chapter** — ask for `ch05`; load that specific chapter
- **Browse** — ask "what chapters do you have?"

## Core Frameworks & Mental Models
<~2,000 tokens: the author's most important named frameworks. Preserve exact
names. Write as "Use X when Y". This is a toolkit, not a summary.>

## Chapter Index
| # | Title | Key Frameworks |
|---|-------|----------------|

## Topic Index
- **<Term>** → ch[, ch]


 glossary.md, patterns.md, cheatsheet.md


This skill covers the book content only.

---

Step 10 — Cleanup and report

Remove the <tempdir>/book_skill_work/ directory after generating. Then report:

✅ Skill created: $SKILLS_HOME/<skill_name>/
📚 Book: <Full Title> — <Author>
📄 Pages: ~<N> | Chapters: <N>
Files generated: SKILL.md, chapters/ (N files), glossary.md, patterns.md, cheatsheet.md
Usage: ask for <skill_name>, or ask about a topic/chapter.
Reload if your agent doesn't auto-detect new skills.

---

Update / Fold-in Workflow

When updating an existing skill at $SKILLS_HOME/<skill_name>/:

1. Read existing structure — parse SKILL.md (Chapter Index, Topic Index, metadata, Core Frameworks); list chapters/ to find the highest chapter number; read glossary/patterns/cheatsheet.
2. Match content — new content is either a revision to an existing chapter (merge) or a new addition (create new numbered chapter files after the highest existing).
3. Generate/update chapters — follow Step 7 formatting.
4. Merge supporting files — alphabetize glossary (append chapter refs to existing terms), append patterns, integrate cheatsheet decision rules.
5. Regenerate SKILL.md — increment chapter count, update page count/date, fold in high-impact frameworks, append new chapters to the index, merge Topic Index alphabetically.
6. Cleanup and report — Step 10 with a custom update summary.

---

Quality Rules

1. Extract structure, not summaries — named frameworks, exact formulations, anti-patterns
2. Preserve the author's precision — keep exact naming
3. Density over completeness — a 1,000-token summary beats a 10,000-token excerpt
4. Practitioner voice — "Use X when Y", not "The book explains X"
5. Front-load SKILL.md — most important content first
6. Chapter files are on-demand — don't count against budget until loaded
7. Never copy raw book text — always synthesize, summarize, extract signal
8. Topic index is critical — it's how the agent navigates to the right chapter

---

Attribution

This is a clean methodology-only port of SKILL.md from virgiliojr94/book-to-skill (MIT). Upstream blocked by SkillSpector (CRITICAL, 100/100) due to bundled Python extraction scripts (subprocess calls, dynamic imports) and privilege references. This port keeps the full prose workflow but replaces the bundled extract.py with the bundle's existing markitdown CLI/MCP for text extraction. No scripts, no deps.