/cs-book-to-skill

name: "cs-book-to-skill"
description: "/cs:book-to-skill <path|folder|glob>... [skill-name] — convert a book, documentation folder, or source collection into a structured agent skill (core frameworks + on-demand chapters + glossary + patterns + cheatsheet). Use when the user wants to study a document with an agent, apply an author's frameworks while working, or turn internal docs into a reusable knowledge base."

/cs:book-to-skill — Compile a Source into an Agent Skill

**Command:** `/cs:book-to-skill <path|folder|glob>... [skill-name-slug]`

Runs the converter end to end: extract → analyze → chapter files → supporting files → master `SKILL.md` → validate. Add "analyze only" to stop after the extraction report.

Pre-flight gates

The command refuses, with a reason, when:

| Gate | Refusal | |------|---------| | No path given | Prints usage. This tool converts files on disk — not titles from memory, not URLs. | | No supported file resolves | Names what was searched and the supported extensions. | | Source is smaller than ~3× the compiled skill | Says converting is not worth it and recommends handing the agent the document. | | Cost estimate not approved | Waits. Generation is the expensive step and the user approves it with numbers in front of them. | | Validation errors after generation | Blocks. Dead chapter links and dangling topic references break navigation silently. |

The six forcing questions

Asked one at a time, each with a recommended answer.

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. `token_budget_estimator.py` prints the verdict.

2. Reference or study?

*Recommended:* reference, unless you intend to internalize the author's reasoning. Study depth roughly doubles generation cost and only earns it with real worked examples.

3. Technical or text?

*Recommended:* technical only when tables, code, or formulas carry meaning. Docling costs ~1.5s/page and buys nothing on a prose book.

4. What will you actually ask this skill?

*Recommended:* name three real questions before generating. They decide what belongs in Core Frameworks and what the topic index must resolve.

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.

6. Does this belong beside an existing skill?

*Recommended:* check for a compiled skill on the same subject first. Folding new sources into one skill beats two skills that half-cover a topic and give the agent no way to choose.

Pipeline

SKILL_ROOT=engineering/book-to-skill/skills/book-to-skill

# 0. environment (optional — reports extractors, installs nothing)
python3 "$SKILL_ROOT/scripts/extract_document.py" --check

# 1. extract
python3 "$SKILL_ROOT/scripts/extract_document.py" <paths> --mode text|technical

# 2. worth-it verdict, before spending a generation pass
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --full-text "$WORKDIR/full_text.txt"

# 3. generate (agent work: chapters, glossary, patterns, cheatsheet, SKILL.md)

# 4. gate
python3 "$SKILL_ROOT/scripts/book_skill_validator.py" "$SKILLS_HOME/<slug>"
python3 "$SKILL_ROOT/scripts/token_budget_estimator.py" --skill-dir "$SKILLS_HOME/<slug>"

Output digest

✅ <slug> — <Title> by <Author>   <N> chapters
   SKILL.md ~<N> tokens (resident) · chapters ~<N> each (on demand)
   validator: <N> error(s), <N> warning(s)
   next: /cs:book-to-plugin to package it for this repo

Related

• `/cs:book-to-plugin` — wrap a compiled skill as a claude-skills plugin
• `/cs:write-a-skill` — author a skill from your own expertise instead of a document