book-to-skill

# Book-to-Skill Converter

Turn written knowledge into an agent skill by extracting **structure**, not summaries.

A book is crystallized expertise: frameworks, principles, techniques that took years to
develop. Read once, forgotten. The workarounds all fail — PDF search returns page numbers
instead of answers, an agent handed the raw file hallucinates or drowns, reading notes rot.
This skill compiles a source into a knowledge base the agent loads on demand: a small
resident core, one chapter file at a time, and never the whole book again.

**What it produces:**

| File | Contents | Budget |
|------|----------|--------|
| `SKILL.md` | Core frameworks + chapter index + topic index | < 4,000 tokens (resident) |
| `chapters/chNN-*.md` | One summary per chapter | 800–3,000 tokens, on demand |
| `glossary.md` | Every significant term, alphabetized, with chapter | < 1,500 tokens |
| `patterns.md` | Techniques and design patterns with trade-offs | < 2,000 tokens |
| `cheatsheet.md` | Decision rules, thresholds, trade-off matrices | < 1,200 tokens |

**Beyond books:** anything referenced often enough to be worth memorizing — internal
documentation, brand systems, standards, specs, research clusters, a folder of RFCs.

---

## Philosophy

**Extract structure, not summaries.** A skill is not a book report. It is a toolkit of
named frameworks, actionable principles, step-by-step techniques, anti-patterns, and the
author's voice.

**Preserve the author's precision.** Framework names are interfaces. "The 5 Whys" is not
interchangeable with "ask why a few times" — the exact formulation is what makes lookup work.

**Layer depth appropriately.** A thin book gets a thin skill. A book with fifteen frameworks
gets chapter files and a real topic index.

**Never reproduce the source at length.** These are structured notes. Synthesize, compress,
name — do not copy passages. See `references/rights_and_provenance.md`.

---

## Modes

| Mode | Trigger | Runs |
|------|---------|------|
| **1. Full conversion** (default) | One or more paths, no special instruction | Steps 0–10 |
| **2. Analyze only** | "analyze", "just extract", "let me review first" | Steps 0–3, then stop with an extraction report |
| **3. Generate from analysis** | User supplies prior analysis notes | Steps 4–10 |
| **4. Update / fold-in** | New sources + an existing compiled skill | Steps 0–2, then the Update Workflow |
| **5. Package as plugin** | "make it a plugin", "add it to the repo" | Step 11 |

Mode 5 is this repository's addition. Upstream stops at a bare folder in a personal skills
home; Step 11 wraps that folder in a plugin package other skills and agents can route to.

---

## Hard rules

1. **Never convert a source the user cannot show you.** No web-scraping a book, no
   reconstructing a title from memory. This tool converts files that are already on disk.
2. **Pre-flight the cost before generating** (Step 2.5). Generation is the expensive part;
   the user approves it with numbers in front of them.
3. **Never dump a large source into context.** Over ~50k tokens, probe with `grep`/`sed`
   and bounded reads (Step 2.6). Re-reading a 200-page book once per chapter costs more
   than everything else in this workflow combined.
4. **Validate before anyone loads it** (Step 9.5). A generated skill is untrusted text that
   an agent will later read as instructions.
5. **Never widen the generated skill's authority.** Generated frontmatter carries `name` and
   `description` only — no `allowed-tools`, no model-invocation flags.
6. **Rights before redistribution.** Compiled notes from a copyrighted work are personal
   study notes. Packaging one as a shareable plugin requires a stated basis (Step 11).
7. **State what the skill does not cover.** Every compiled skill's Scope section names its
   boundary, so the agent says "the source doesn't cover this" instead of improvising.

---

## Pipeline

```
extract_document.py  →  analyze  →  chapter files  →  supporting files  →  SKILL.md
      (Step 2)          (Step 3)      (Step 7)          (Step 8)          (Step 9)
                                                                              ↓
                                       skill_plugin_emitter.py  ←  book_skill_validator.py
                                              (Step 11)                  (Step 9.5)
```

All four tools live in `scripts/` and run on the standard library alone.

---

## Run it

```bash
SKILL_ROOT=engineering/book-to-skill/skills/book-to-skill
SKILLS_HOME=~/.claude/skills        # Step 5 picks this; see the workflow reference
WORKDIR=$(mktemp -d)                # or omit --workdir and capture the path it prints
SLUG=<author-lastname>-<concept>

# 1. extract → $WORKDIR/full_text.txt + metadata.json
#    --mode technical when tables, code or formulas carry meaning
python3 "$SKILL_ROOT/scripts/extract_document.py" <paths> --mode text --workdir "$WORKDIR"

# 2. pre-flight: is this worth converting at all? Wait for approval before generating.
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --full-text "$WORKDIR/full_text.txt"

# 3. generate — the agent's work: chapters/, glossary, patterns, cheatsheet, SKILL.md

# 4. gate — errors block. Fix and re-run; never rewrite around a finding.
python3 "$SKILL_ROOT/scripts/book_skill_validator.py" "$SKILLS_HOME/$SLUG"
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --skill-dir "$SKILLS_HOME/$SLUG"

# 5. optional: wrap as a claude-skills plugin so the library can route to it
python3 "$SKILL_ROOT/scripts/skill_plugin_emitter.py" --skill-dir "$SKILLS_HOME/$SLUG" \
    --dest ./engineering --source-note "<Title> by <Author>" --dry-run
```

Every path above is a real variable, not a placeholder: run the block as written (with
`<paths>` and `$SLUG` filled in) and it works end to end. Without `--workdir` the extractor
creates a private temp directory and prints it — capture that instead.

`extract_document.py --check` reports which extractors are installed and prints the install
command for what is missing. Every tool supports `--help`, `--sample` and `--output json`.

**The full step-by-step procedure — what to ask at each step, the file templates, the
per-chapter budget matrix, and the update/fold-in workflow — is in
[`references/conversion_workflow.md`](references/conversion_workflow.md). Read it before
running a conversion.** Summary of the eleven steps:

| Step | Does |
|------|------|
| 0–1 | Scope check; resolve paths; detect an update/fold-in against an existing skill |
| 1.5 | Ask content type → `BOOK_TYPE` (technical vs. text), which picks the extractor |
| 2 | Extract → `full_text.txt` + `metadata.json` |
| 2.5 | Pre-flight cost estimate and worth-converting verdict — **wait for approval** |
| 2.6 | Over ~50k tokens, probe with `grep`/`sed` instead of reading the source |
| 3 | Analyze structure (title, author, chapters, themes). Mode 2 stops here. |
| 4 | Ask purpose → `DEPTH` (reference vs. study). Never ask a second budget question. |
| 5 | Skill name and destination root; offer update / overwrite / rename on a collision |
| 6–8 | Create the structure; write chapter files; write glossary, patterns, cheatsheet |
| 9 | Write the master `SKILL.md` — under 4,000 tokens, indexes intact |
| 9.5 | Validate. Errors block. |
| 10 | Clean up the workdir and report |
| 11 | Optionally package as a plugin, behind the rights gate |

## Validator findings worth knowing

| Rule | Means |
|------|-------|
| `index.dead_link` | The chapter index links a file that was never written |
| `index.topic_dangling` | A topic points at a chapter that does not exist |
| `budget.over_cap` on SKILL.md | Compaction will truncate the indexes — navigation is the first thing lost |
| `unicode.invisible` | Extraction should have stripped this; investigate the source |
| `frontmatter.allowed_tools` | The generated skill is trying to grant itself tool authority |

Safety-family warnings are deliberately broad — a source about prompt injection legitimately
trips them. Read each in context; do not auto-silence them.

## Forcing-question library

Walk these one at a time, with a recommended answer, before running a conversion.

1. **"Is this source worth converting, or should I just read it?"**
   *Recommended:* convert when it is > 3× the compiled skill's size **and** you will return
   to it. One-shot reads are cheaper unconverted. (Step 2.5 verdict.)

2. **"Reference or study?"**
   *Recommended:* reference, unless you intend to internalize the author's reasoning. Study
   depth roughly doubles generation cost and is only worth it with real worked examples.
   (Step 4.)

3. **"Technical or text?"**
   *Recommended:* technical only when tables, code, or formulas carry meaning. Docling costs
   ~1.5s/page; picking it for a prose book buys nothing. (Step 1.5.)

4. **"What will you actually ask this skill?"**
   *Recommended:* name three real questions before generating. They tell you what belongs in
   Core Frameworks and what the topic index must resolve. A skill nobody queries is a
   summary nobody reads.

5. **"Do you have the right to redistribute this?"**
   *Recommended:* assume not. Keep it local unless the source is public-domain, openly
   licensed, your organisation's own documentation, or you have written permission.
   (Step 11 rights gate.)

6. **"Does this belong beside an existing skill?"**
   *Recommended:* check for an existing compiled skill on the same subject first — folding
   new sources into one skill (Mode 4) beats two skills that half-cover a topic and give
   the agent no way to choose. (Step 0.)

---

## References

- `references/conversion_workflow.md` — **the full procedure**: Steps 0–11, the file
  templates, the per-chapter budget matrix, and the update/fold-in workflow
- `references/knowledge_extraction_canon.md` — why structure beats summary; the extraction
  taxonomy; what makes a framework survive compression
- `references/progressive_disclosure_budgets.md` — where the token budgets come from and
  what breaks when they are exceeded
- `references/document_extraction_pipeline.md` — per-format extractor chains, fallbacks,
  and the failure modes that produce silently bad text
- `references/rights_and_provenance.md` — copyright posture, the rights gate, and what
  provenance a compiled skill must carry

## Related skills

- **`engineering/write-a-skill`** — authoring a skill from your own expertise. Use that when
  the knowledge is in your head; use this when it is in a document.
- **`engineering/skill-security-auditor`** — full security audit of a skill package. Step 9.5
  is the converter's own gate; the auditor is the repo-wide one.
- **`engineering/llm-wiki`** — an incrementally-grown, interlinked vault across many sources.
  This skill compiles one bounded source set into one skill.

---

*Adapted from [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) (MIT).
See `../../README.md` for the full list of deviations.*

{
  "format": "aiskill/v1",
  "skill": {
    "name": "book-to-skill",
    "slug": "book-to-skill",
    "version": "1.0.0",
    "description": "Converts books, documentation folders, and source collections (PDF, EPUB, DOCX, HTML, Markdown, RST, AsciiDoc, RTF, MOBI/AZW) into structured agent skills — extracting named frameworks, principles, techniques, and anti-patterns into a master SKILL.md plus on-demand chapter files, a glossary, a patterns file, and a decision cheatsheet. Use when the user wants to study a document with an agent, apply an author's frameworks while working, turn internal docs or standards into a reusable knowledge base, or package a compiled book skill as a claude-skills plugin.",
    "category": "Development",
    "tags": [
      "ai-agents",
      "agents",
      "documents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Book-to-Skill Converter\r\n\r\nTurn written knowledge into an agent skill by extracting **structure**, not summaries.\r\n\r\nA book is crystallized expertise: frameworks, principles, techniques that took years to\r\ndevelop. Read once, forgotten. The workarounds all fail — PDF search returns page numbers\r\ninstead of answers, an agent handed the raw file hallucinates or drowns, reading notes rot.\r\nThis skill compiles a source into a knowledge base the agent loads on demand: a small\r\nresident core, one chapter file at a time, and never the whole book again.\r\n\r\n**What it produces:**\r\n\r\n| File | Contents | Budget |\r\n|------|----------|--------|\r\n| `SKILL.md` | Core frameworks + chapter index + topic index | < 4,000 tokens (resident) |\r\n| `chapters/chNN-*.md` | One summary per chapter | 800–3,000 tokens, on demand |\r\n| `glossary.md` | Every significant term, alphabetized, with chapter | < 1,500 tokens |\r\n| `patterns.md` | Techniques and design patterns with trade-offs | < 2,000 tokens |\r\n| `cheatsheet.md` | Decision rules, thresholds, trade-off matrices | < 1,200 tokens |\r\n\r\n**Beyond books:** anything referenced often enough to be worth memorizing — internal\r\ndocumentation, brand systems, standards, specs, research clusters, a folder of RFCs.\r\n\r\n---\r\n\r\n## Philosophy\r\n\r\n**Extract structure, not summaries.** A skill is not a book report. It is a toolkit of\r\nnamed frameworks, actionable principles, step-by-step techniques, anti-patterns, and the\r\nauthor's voice.\r\n\r\n**Preserve the author's precision.** Framework names are interfaces. \"The 5 Whys\" is not\r\ninterchangeable with \"ask why a few times\" — the exact formulation is what makes lookup work.\r\n\r\n**Layer depth appropriately.** A thin book gets a thin skill. A book with fifteen frameworks\r\ngets chapter files and a real topic index.\r\n\r\n**Never reproduce the source at length.** These are structured notes. Synthesize, compress,\r\nname — do not copy passages. See `references/rights_and_provenance.md`.\r\n\r\n---\r\n\r\n## Modes\r\n\r\n| Mode | Trigger | Runs |\r\n|------|---------|------|\r\n| **1. Full conversion** (default) | One or more paths, no special instruction | Steps 0–10 |\r\n| **2. Analyze only** | \"analyze\", \"just extract\", \"let me review first\" | Steps 0–3, then stop with an extraction report |\r\n| **3. Generate from analysis** | User supplies prior analysis notes | Steps 4–10 |\r\n| **4. Update / fold-in** | New sources + an existing compiled skill | Steps 0–2, then the Update Workflow |\r\n| **5. Package as plugin** | \"make it a plugin\", \"add it to the repo\" | Step 11 |\r\n\r\nMode 5 is this repository's addition. Upstream stops at a bare folder in a personal skills\r\nhome; Step 11 wraps that folder in a plugin package other skills and agents can route to.\r\n\r\n---\r\n\r\n## Hard rules\r\n\r\n1. **Never convert a source the user cannot show you.** No web-scraping a book, no\r\n   reconstructing a title from memory. This tool converts files that are already on disk.\r\n2. **Pre-flight the cost before generating** (Step 2.5). Generation is the expensive part;\r\n   the user approves it with numbers in front of them.\r\n3. **Never dump a large source into context.** Over ~50k tokens, probe with `grep`/`sed`\r\n   and bounded reads (Step 2.6). Re-reading a 200-page book once per chapter costs more\r\n   than everything else in this workflow combined.\r\n4. **Validate before anyone loads it** (Step 9.5). A generated skill is untrusted text that\r\n   an agent will later read as instructions.\r\n5. **Never widen the generated skill's authority.** Generated frontmatter carries `name` and\r\n   `description` only — no `allowed-tools`, no model-invocation flags.\r\n6. **Rights before redistribution.** Compiled notes from a copyrighted work are personal\r\n   study notes. Packaging one as a shareable plugin requires a stated basis (Step 11).\r\n7. **State what the skill does not cover.** Every compiled skill's Scope section names its\r\n   boundary, so the agent says \"the source doesn't cover this\" instead of improvising.\r\n\r\n---\r\n\r\n## Pipeline\r\n\r\n```\r\nextract_document.py  →  analyze  →  chapter files  →  supporting files  →  SKILL.md\r\n      (Step 2)          (Step 3)      (Step 7)          (Step 8)          (Step 9)\r\n                                                                              ↓\r\n                                       skill_plugin_emitter.py  ←  book_skill_validator.py\r\n                                              (Step 11)                  (Step 9.5)\r\n```\r\n\r\nAll four tools live in `scripts/` and run on the standard library alone.\r\n\r\n---\r\n\r\n## Run it\r\n\r\n```bash\r\nSKILL_ROOT=engineering/book-to-skill/skills/book-to-skill\r\nSKILLS_HOME=~/.claude/skills        # Step 5 picks this; see the workflow reference\r\nWORKDIR=$(mktemp -d)                # or omit --workdir and capture the path it prints\r\nSLUG=<author-lastname>-<concept>\r\n\r\n# 1. extract → $WORKDIR/full_text.txt + metadata.json\r\n#    --mode technical when tables, code or formulas carry meaning\r\npython3 \"$SKILL_ROOT/scripts/extract_document.py\" <paths> --mode text --workdir \"$WORKDIR\"\r\n\r\n# 2. pre-flight: is this worth converting at all? Wait for approval before generating.\r\npython3 \"$SKILL_ROOT/scripts/token_budget_estimator.py\" --full-text \"$WORKDIR/full_text.txt\"\r\n\r\n# 3. generate — the agent's work: chapters/, glossary, patterns, cheatsheet, SKILL.md\r\n\r\n# 4. gate — errors block. Fix and re-run; never rewrite around a finding.\r\npython3 \"$SKILL_ROOT/scripts/book_skill_validator.py\" \"$SKILLS_HOME/$SLUG\"\r\npython3 \"$SKILL_ROOT/scripts/token_budget_estimator.py\" --skill-dir \"$SKILLS_HOME/$SLUG\"\r\n\r\n# 5. optional: wrap as a claude-skills plugin so the library can route to it\r\npython3 \"$SKILL_ROOT/scripts/skill_plugin_emitter.py\" --skill-dir \"$SKILLS_HOME/$SLUG\" \\\r\n    --dest ./engineering --source-note \"<Title> by <Author>\" --dry-run\r\n```\r\n\r\nEvery path above is a real variable, not a placeholder: run the block as written (with\r\n`<paths>` and `$SLUG` filled in) and it works end to end. Without `--workdir` the extractor\r\ncreates a private temp directory and prints it — capture that instead.\r\n\r\n`extract_document.py --check` reports which extractors are installed and prints the install\r\ncommand for what is missing. Every tool supports `--help`, `--sample` and `--output json`.\r\n\r\n**The full step-by-step procedure — what to ask at each step, the file templates, the\r\nper-chapter budget matrix, and the update/fold-in workflow — is in\r\n[`references/conversion_workflow.md`](references/conversion_workflow.md). Read it before\r\nrunning a conversion.** Summary of the eleven steps:\r\n\r\n| Step | Does |\r\n|------|------|\r\n| 0–1 | Scope check; resolve paths; detect an update/fold-in against an existing skill |\r\n| 1.5 | Ask content type → `BOOK_TYPE` (technical vs. text), which picks the extractor |\r\n| 2 | Extract → `full_text.txt` + `metadata.json` |\r\n| 2.5 | Pre-flight cost estimate and worth-converting verdict — **wait for approval** |\r\n| 2.6 | Over ~50k tokens, probe with `grep`/`sed` instead of reading the source |\r\n| 3 | Analyze structure (title, author, chapters, themes). Mode 2 stops here. |\r\n| 4 | Ask purpose → `DEPTH` (reference vs. study). Never ask a second budget question. |\r\n| 5 | Skill name and destination root; offer update / overwrite / rename on a collision |\r\n| 6–8 | Create the structure; write chapter files; write glossary, patterns, cheatsheet |\r\n| 9 | Write the master `SKILL.md` — under 4,000 tokens, indexes intact |\r\n| 9.5 | Validate. Errors block. |\r\n| 10 | Clean up the workdir and report |\r\n| 11 | Optionally package as a plugin, behind the rights gate |\r\n\r\n## Validator findings worth knowing\r\n\r\n| Rule | Means |\r\n|------|-------|\r\n| `index.dead_link` | The chapter index links a file that was never written |\r\n| `index.topic_dangling` | A topic points at a chapter that does not exist |\r\n| `budget.over_cap` on SKILL.md | Compaction will truncate the indexes — navigation is the first thing lost |\r\n| `unicode.invisible` | Extraction should have stripped this; investigate the source |\r\n| `frontmatter.allowed_tools` | The generated skill is trying to grant itself tool authority |\r\n\r\nSafety-family warnings are deliberately broad — a source about prompt injection legitimately\r\ntrips them. Read each in context; do not auto-silence them.\r\n\r\n## Forcing-question library\r\n\r\nWalk these one at a time, with a recommended answer, before running a conversion.\r\n\r\n1. **\"Is this source worth converting, or should I just read it?\"**\r\n   *Recommended:* convert when it is > 3× the compiled skill's size **and** you will return\r\n   to it. One-shot reads are cheaper unconverted. (Step 2.5 verdict.)\r\n\r\n2. **\"Reference or study?\"**\r\n   *Recommended:* reference, unless you intend to internalize the author's reasoning. Study\r\n   depth roughly doubles generation cost and is only worth it with real worked examples.\r\n   (Step 4.)\r\n\r\n3. **\"Technical or text?\"**\r\n   *Recommended:* technical only when tables, code, or formulas carry meaning. Docling costs\r\n   ~1.5s/page; picking it for a prose book buys nothing. (Step 1.5.)\r\n\r\n4. **\"What will you actually ask this skill?\"**\r\n   *Recommended:* name three real questions before generating. They tell you what belongs in\r\n   Core Frameworks and what the topic index must resolve. A skill nobody queries is a\r\n   summary nobody reads.\r\n\r\n5. **\"Do you have the right to redistribute this?\"**\r\n   *Recommended:* assume not. Keep it local unless the source is public-domain, openly\r\n   licensed, your organisation's own documentation, or you have written permission.\r\n   (Step 11 rights gate.)\r\n\r\n6. **\"Does this belong beside an existing skill?\"**\r\n   *Recommended:* check for an existing compiled skill on the same subject first — folding\r\n   new sources into one skill (Mode 4) beats two skills that half-cover a topic and give\r\n   the agent no way to choose. (Step 0.)\r\n\r\n---\r\n\r\n## References\r\n\r\n- `references/conversion_workflow.md` — **the full procedure**: Steps 0–11, the file\r\n  templates, the per-chapter budget matrix, and the update/fold-in workflow\r\n- `references/knowledge_extraction_canon.md` — why structure beats summary; the extraction\r\n  taxonomy; what makes a framework survive compression\r\n- `references/progressive_disclosure_budgets.md` — where the token budgets come from and\r\n  what breaks when they are exceeded\r\n- `references/document_extraction_pipeline.md` — per-format extractor chains, fallbacks,\r\n  and the failure modes that produce silently bad text\r\n- `references/rights_and_provenance.md` — copyright posture, the rights gate, and what\r\n  provenance a compiled skill must carry\r\n\r\n## Related skills\r\n\r\n- **`engineering/write-a-skill`** — authoring a skill from your own expertise. Use that when\r\n  the knowledge is in your head; use this when it is in a document.\r\n- **`engineering/skill-security-auditor`** — full security audit of a skill package. Step 9.5\r\n  is the converter's own gate; the auditor is the repo-wide one.\r\n- **`engineering/llm-wiki`** — an incrementally-grown, interlinked vault across many sources.\r\n  This skill compiles one bounded source set into one skill.\r\n\r\n---\r\n\r\n*Adapted from [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) (MIT).\r\nSee `../../README.md` for the full list of deviations.*",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The book-to-skill/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/book-to-skill",
    "exported_at": "2026-11-03T07:44:37.391Z"
  }
}

format: aiskill/v1
skill:
  name: book-to-skill
  slug: book-to-skill
  version: 1.0.0
  description: >-
    Converts books, documentation folders, and source collections (PDF, EPUB, DOCX, HTML, Markdown,
    RST, AsciiDoc, RTF, MOBI/AZW) into structured agent skills — extracting named frameworks,
    principles, techniques, and anti-patterns into a master SKILL.md plus on-demand chapter files, a
    glossary, a patterns file, and a decision cheatsheet. Use when the user wants to study a
    document with an agent, apply an author's frameworks while working, turn internal docs or
    standards into a reusable knowledge base, or package a compiled book skill as a claude-skills
    plugin.
  category: Development
  tags:
    - ai-agents
    - agents
    - documents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Book-to-Skill Converter\r\n\r\nTurn written knowledge into an agent skill by extracting **structure**, not summaries.\r\n\r\nA book is crystallized expertise: frameworks, principles, techniques that took years to\r\ndevelop. Read once, forgotten. The workarounds all fail — PDF search returns page numbers\r\ninstead of answers, an agent handed the raw file hallucinates or drowns, reading notes rot.\r\nThis skill compiles a source into a knowledge base the agent loads on demand: a small\r\nresident core, one chapter file at a time, and never the whole book again.\r\n\r\n**What it produces:**\r\n\r\n| File | Contents | Budget |\r\n|------|----------|--------|\r\n| `SKILL.md` | Core frameworks + chapter index + topic index | < 4,000 tokens (resident) |\r\n| `chapters/chNN-*.md` | One summary per chapter | 800–3,000 tokens, on demand |\r\n| `glossary.md` | Every significant term, alphabetized, with chapter | < 1,500 tokens |\r\n| `patterns.md` | Techniques and design patterns with trade-offs | < 2,000 tokens |\r\n| `cheatsheet.md` | Decision rules, thresholds, trade-off matrices | < 1,200 tokens |\r\n\r\n**Beyond books:** anything referenced often enough to be worth memorizing — internal\r\ndocumentation, brand systems, standards, specs, research clusters, a folder of RFCs.\r\n\r\n---\r\n\r\n## Philosophy\r\n\r\n**Extract structure, not summaries.** A skill is not a book report. It is a toolkit of\r\nnamed frameworks, actionable principles, step-by-step techniques, anti-patterns, and the\r\nauthor's voice.\r\n\r\n**Preserve the author's precision.** Framework names are interfaces. \"The 5 Whys\" is not\r\ninterchangeable with \"ask why a few times\" — the exact formulation is what makes lookup work.\r\n\r\n**Layer depth appropriately.** A thin book gets a thin skill. A book with fifteen frameworks\r\ngets chapter files and a real topic index.\r\n\r\n**Never reproduce the source at length.** These are structured notes. Synthesize, compress,\r\nname — do not copy passages. See `references/rights_and_provenance.md`.\r\n\r\n---\r\n\r\n## Modes\r\n\r\n| Mode | Trigger | Runs |\r\n|------|---------|------|\r\n| **1. Full conversion** (default) | One or more paths, no special instruction | Steps 0–10 |\r\n| **2. Analyze only** | \"analyze\", \"just extract\", \"let me review first\" | Steps 0–3, then stop with an extraction report |\r\n| **3. Generate from analysis** | User supplies prior analysis notes | Steps 4–10 |\r\n| **4. Update / fold-in** | New sources + an existing compiled skill | Steps 0–2, then the Update Workflow |\r\n| **5. Package as plugin** | \"make it a plugin\", \"add it to the repo\" | Step 11 |\r\n\r\nMode 5 is this repository's addition. Upstream stops at a bare folder in a personal skills\r\nhome; Step 11 wraps that folder in a plugin package other skills and agents can route to.\r\n\r\n---\r\n\r\n## Hard rules\r\n\r\n1. **Never convert a source the user cannot show you.** No web-scraping a book, no\r\n   reconstructing a title from memory. This tool converts files that are already on disk.\r\n2. **Pre-flight the cost before generating** (Step 2.5). Generation is the expensive part;\r\n   the user approves it with numbers in front of them.\r\n3. **Never dump a large source into context.** Over ~50k tokens, probe with `grep`/`sed`\r\n   and bounded reads (Step 2.6). Re-reading a 200-page book once per chapter costs more\r\n   than everything else in this workflow combined.\r\n4. **Validate before anyone loads it** (Step 9.5). A generated skill is untrusted text that\r\n   an agent will later read as instructions.\r\n5. **Never widen the generated skill's authority.** Generated frontmatter carries `name` and\r\n   `description` only — no `allowed-tools`, no model-invocation flags.\r\n6. **Rights before redistribution.** Compiled notes from a copyrighted work are personal\r\n   study notes. Packaging one as a shareable plugin requires a stated basis (Step 11).\r\n7. **State what the skill does not cover.** Every compiled skill's Scope section names its\r\n   boundary, so the agent says \"the source doesn't cover this\" instead of improvising.\r\n\r\n---\r\n\r\n## Pipeline\r\n\r\n```\r\nextract_document.py  →  analyze  →  chapter files  →  supporting files  →  SKILL.md\r\n      (Step 2)          (Step 3)      (Step 7)          (Step 8)          (Step 9)\r\n                                                                              ↓\r\n                                       skill_plugin_emitter.py  ←  book_skill_validator.py\r\n                                              (Step 11)                  (Step 9.5)\r\n```\r\n\r\nAll four tools live in `scripts/` and run on the standard library alone.\r\n\r\n---\r\n\r\n## Run it\r\n\r\n```bash\r\nSKILL_ROOT=engineering/book-to-skill/skills/book-to-skill\r\nSKILLS_HOME=~/.claude/skills        # Step 5 picks this; see the workflow reference\r\nWORKDIR=$(mktemp -d)                # or omit --workdir and capture the path it prints\r\nSLUG=<author-lastname>-<concept>\r\n\r\n# 1. extract → $WORKDIR/full_text.txt + metadata.json\r\n#    --mode technical when tables, code or formulas carry meaning\r\npython3 \"$SKILL_ROOT/scripts/extract_document.py\" <paths> --mode text --workdir \"$WORKDIR\"\r\n\r\n# 2. pre-flight: is this worth converting at all? Wait for approval before generating.\r\npython3 \"$SKILL_ROOT/scripts/token_budget_estimator.py\" --full-text \"$WORKDIR/full_text.txt\"\r\n\r\n# 3. generate — the agent's work: chapters/, glossary, patterns, cheatsheet, SKILL.md\r\n\r\n# 4. gate — errors block. Fix and re-run; never rewrite around a finding.\r\npython3 \"$SKILL_ROOT/scripts/book_skill_validator.py\" \"$SKILLS_HOME/$SLUG\"\r\npython3 \"$SKILL_ROOT/scripts/token_budget_estimator.py\" --skill-dir \"$SKILLS_HOME/$SLUG\"\r\n\r\n# 5. optional: wrap as a claude-skills plugin so the library can route to it\r\npython3 \"$SKILL_ROOT/scripts/skill_plugin_emitter.py\" --skill-dir \"$SKILLS_HOME/$SLUG\" \\\r\n    --dest ./engineering --source-note \"<Title> by <Author>\" --dry-run\r\n```\r\n\r\nEvery path above is a real variable, not a placeholder: run the block as written (with\r\n`<paths>` and `$SLUG` filled in) and it works end to end. Without `--workdir` the extractor\r\ncreates a private temp directory and prints it — capture that instead.\r\n\r\n`extract_document.py --check` reports which extractors are installed and prints the install\r\ncommand for what is missing. Every tool supports `--help`, `--sample` and `--output json`.\r\n\r\n**The full step-by-step procedure — what to ask at each step, the file templates, the\r\nper-chapter budget matrix, and the update/fold-in workflow — is in\r\n[`references/conversion_workflow.md`](references/conversion_workflow.md). Read it before\r\nrunning a conversion.** Summary of the eleven steps:\r\n\r\n| Step | Does |\r\n|------|------|\r\n| 0–1 | Scope check; resolve paths; detect an update/fold-in against an existing skill |\r\n| 1.5 | Ask content type → `BOOK_TYPE` (technical vs. text), which picks the extractor |\r\n| 2 | Extract → `full_text.txt` + `metadata.json` |\r\n| 2.5 | Pre-flight cost estimate and worth-converting verdict — **wait for approval** |\r\n| 2.6 | Over ~50k tokens, probe with `grep`/`sed` instead of reading the source |\r\n| 3 | Analyze structure (title, author, chapters, themes). Mode 2 stops here. |\r\n| 4 | Ask purpose → `DEPTH` (reference vs. study). Never ask a second budget question. |\r\n| 5 | Skill name and destination root; offer update / overwrite / rename on a collision |\r\n| 6–8 | Create the structure; write chapter files; write glossary, patterns, cheatsheet |\r\n| 9 | Write the master `SKILL.md` — under 4,000 tokens, indexes intact |\r\n| 9.5 | Validate. Errors block. |\r\n| 10 | Clean up the workdir and report |\r\n| 11 | Optionally package as a plugin, behind the rights gate |\r\n\r\n## Validator findings worth knowing\r\n\r\n| Rule | Means |\r\n|------|-------|\r\n| `index.dead_link` | The chapter index links a file that was never written |\r\n| `index.topic_dangling` | A topic points at a chapter that does not exist |\r\n| `budget.over_cap` on SKILL.md | Compaction will truncate the indexes — navigation is the first thing lost |\r\n| `unicode.invisible` | Extraction should have stripped this; investigate the source |\r\n| `frontmatter.allowed_tools` | The generated skill is trying to grant itself tool authority |\r\n\r\nSafety-family warnings are deliberately broad — a source about prompt injection legitimately\r\ntrips them. Read each in context; do not auto-silence them.\r\n\r\n## Forcing-question library\r\n\r\nWalk these one at a time, with a recommended answer, before running a conversion.\r\n\r\n1. **\"Is this source worth converting, or should I just read it?\"**\r\n   *Recommended:* convert when it is > 3× the compiled skill's size **and** you will return\r\n   to it. One-shot reads are cheaper unconverted. (Step 2.5 verdict.)\r\n\r\n2. **\"Reference or study?\"**\r\n   *Recommended:* reference, unless you intend to internalize the author's reasoning. Study\r\n   depth roughly doubles generation cost and is only worth it with real worked examples.\r\n   (Step 4.)\r\n\r\n3. **\"Technical or text?\"**\r\n   *Recommended:* technical only when tables, code, or formulas carry meaning. Docling costs\r\n   ~1.5s/page; picking it for a prose book buys nothing. (Step 1.5.)\r\n\r\n4. **\"What will you actually ask this skill?\"**\r\n   *Recommended:* name three real questions before generating. They tell you what belongs in\r\n   Core Frameworks and what the topic index must resolve. A skill nobody queries is a\r\n   summary nobody reads.\r\n\r\n5. **\"Do you have the right to redistribute this?\"**\r\n   *Recommended:* assume not. Keep it local unless the source is public-domain, openly\r\n   licensed, your organisation's own documentation, or you have written permission.\r\n   (Step 11 rights gate.)\r\n\r\n6. **\"Does this belong beside an existing skill?\"**\r\n   *Recommended:* check for an existing compiled skill on the same subject first — folding\r\n   new sources into one skill (Mode 4) beats two skills that half-cover a topic and give\r\n   the agent no way to choose. (Step 0.)\r\n\r\n---\r\n\r\n## References\r\n\r\n- `references/conversion_workflow.md` — **the full procedure**: Steps 0–11, the file\r\n  templates, the per-chapter budget matrix, and the update/fold-in workflow\r\n- `references/knowledge_extraction_canon.md` — why structure beats summary; the extraction\r\n  taxonomy; what makes a framework survive compression\r\n- `references/progressive_disclosure_budgets.md` — where the token budgets come from and\r\n  what breaks when they are exceeded\r\n- `references/document_extraction_pipeline.md` — per-format extractor chains, fallbacks,\r\n  and the failure modes that produce silently bad text\r\n- `references/rights_and_provenance.md` — copyright posture, the rights gate, and what\r\n  provenance a compiled skill must carry\r\n\r\n## Related skills\r\n\r\n- **`engineering/write-a-skill`** — authoring a skill from your own expertise. Use that when\r\n  the knowledge is in your head; use this when it is in a document.\r\n- **`engineering/skill-security-auditor`** — full security audit of a skill package. Step 9.5\r\n  is the converter's own gate; the auditor is the repo-wide one.\r\n- **`engineering/llm-wiki`** — an incrementally-grown, interlinked vault across many sources.\r\n  This skill compiles one bounded source set into one skill.\r\n\r\n---\r\n\r\n*Adapted from [virgiliojr94/book-to-skill](https://github.com/virgiliojr94/book-to-skill) (MIT).\r\nSee `../../README.md` for the full list of deviations.*"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The book-to-skill/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/book-to-skill
  exported_at: "2026-11-03T07:44:37.391Z"