/cs-book-to-skill¶

Slash Command Source

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

/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