/book-to-skill

name: book-to-skill
description: "Converts books and documents (PDF, EPUB, DOCX, HTML, Markdown, plain text, RTF, MOBI/AZW with Calibre) into structured agent skills, extracting frameworks, mental models, principles, techniques, and anti-patterns. Use when the user wants to study a document through GitHub Copilot CLI, Amp, Claude Code, Hermes Agent, OpenCode, or OpenClaw, apply an author's frameworks while working, or build a reusable knowledge base from a file."

<!-- Cross-agent notes (informational; ignored by host agents):

• Compatible skill roots: GitHub Copilot CLI (~/.copilot/skills, ~/.agents/skills,

.github/skills, .claude/skills, .agents/skills), Amp (.agents/skills, ~/.config/agents/skills, ~/.config/amp/skills), Claude Code (~/.claude/skills), Hermes Agent ($HERMES_HOME/skills, .hermes/skills, .agents/skills), OpenClaw (${OPENCLAW_STATE_DIR:-~/.openclaw}/skills, .agents/skills, skills/; ~/.agents/skills only with the default state). OpenCode (~/.config/opencode/skills, ~/.claude/skills, .opencode/skills, ~/.agents/skills, .agents/skills).

• `allowed-tools` is intentionally omitted to stay agent-neutral: Copilot CLI uses

`shell`/MCP-server names, Claude uses `Bash`/`Read`/`Write`/`Glob`/`Grep`, Amp adds `shell_command`. The skill needs shell (to run extract.py) and file read/write — each host will prompt for those on first use.

• Argument hint: <path-to-document-folder-or-glob>... [skill-name-slug]

-->

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 GitHub Copilot CLI, Amp, Claude Code, Hermes Agent, OpenCode, OpenClaw, or another compatible 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 (frameworks, principles, techniques found). 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 one or more new source paths and indicates they want to update an existing skill (either by pointing to the existing skill folder, providing a skill slug that already exists in `SKILLS_HOME`, or explicitly requesting an update). **Action:** Run Step 0 (out-of-scope check), Step 1 (validate inputs), Step 1.5 (identify book type), and Step 2 (extract new files). Then skip to Step 5 (identify/detect existing skill path) and run the **Update / Fold-in Workflow** to merge the new content into the existing skill files. **Output:** Updated existing skill with new/revised chapter summaries and merged indexes/glossaries.

---

Skill Locations

This converter can run from multiple skill systems. When looking for this converter's helper script or writing the generated book skill, prefer these locations in order:

1. GitHub Copilot CLI personal skills: `~/.copilot/skills/` 2. Cross-agent personal skills (Copilot, Amp, Codex; OpenClaw with its default state): `~/.agents/skills/` 3. Claude Code personal skills: `~/.claude/skills/` 4. Project-local Copilot skills: `.github/skills/` 5. Project-local Claude skills: `.claude/skills/` 6. Project-local Amp / Copilot / OpenClaw skills: `.agents/skills/` 7. Amp global skills: `~/.config/agents/skills/` 8. Amp legacy global skills: `~/.config/amp/skills/` 9. Hermes Agent personal skills: `$HERMES_HOME/skills/` (defaults to `~/.hermes/skills/`) 10. Hermes Agent project skills: `.hermes/skills/` or `.agents/skills/` 11. OpenClaw personal skills: `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills/` (active state; `~/.agents/skills/` is shared only with the default state) 12. OpenClaw project skills: `.agents/skills/` or `skills/` 11. OpenCode personal skills: `~/.config/opencode/skills/` or `~/.agents/skills/` 12. OpenCode project skills: `.opencode/skills/` or `.agents/skills/`

For **generated** book skills, prefer the user-level cross-agent root `~/.agents/skills/` — one physical copy serves the cross-agent hosts and OpenClaw when it uses its default state. Copilot CLI and Amp discover it natively; Claude Code needs a symlink from `~/.claude/skills/<skill_name>` (created in Step 10, see Step 5 for the rules). Pick a host-private or project-local root only when the user explicitly asks for one. `BOOK_TO_SKILL_SCOPE=project` or `personal` can make that choice explicit for automation; do not ask a mandatory scope question merely because both scopes are available.

---

Step 0 — O