# Book Compiler

> Turns a book on writing, editing, communication, rhetoric, storytelling, or copywriting into an executable Claude skill that performs the book's method rather than summarizing it. Use when the user supplies a book (PDF, EPUB, DOCX, or extracted text) and wants a skill built from it, wants an existing skill audited or rebuilt against its source book, or wants a library of books processed into skills.

- Skill: `immeasurablematt/book-compiler` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add immeasurablematt/book-compiler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/immeasurablematt/book-compiler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: immeasurablematt (https://skillmd.com/u/immeasurablematt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/immeasurablematt/book-compiler

---


# Book Compiler

A book is written to be **read**. A skill is written to be **run**. The job is to
convert one into the other, so that every method the book teaches becomes
something the agent does — with a trigger, a diagnostic, an action, and a check.

Two rules bind the whole build:

- **Provenance** — every runtime rule traces to a source unit or is labeled an
  adaptation. Facts, numbers, and uncertainty survive; nothing invented is
  presented as sourced.
- **Theatre** — file counts, chapter titles, unrun model claims, and green exit
  codes are not evidence of work. Claim only what you inspected.

`$ARGUMENTS` holds source paths, an existing-skill path, or scope instructions.

## Modes

The build runs at one of three depths. Pick the shallowest that meets the user's
real goal: the full pipeline exists for skills that will be *distributed*, and
forcing it on someone who only wants a book's method for their own use is wasted
work.

- **map** — inventory the source and build the source-method map, then stop and
  show it. Answers "what's in here, and is it worth building?" (Phases 1–3.)
- **draft** — map, then write a working skill with a few smoke evals and a
  structural validation. The default: it produces something installable and
  usable today. (Phases 1–6, plus a light Phase 8 and Phase 9.)
- **ship** — draft plus the full source-fidelity audit, the four-layer
  regression suite, and the packaging gate. For a skill going to other people.
  (All phases.)

Before the expensive phases, state the source size, the chosen mode, and what the
run will produce, then confirm the mode. Give effort in relative terms; avoid a
priced estimate, since model prices go stale and become a maintenance trap.

## Workflow

### Phase 1 — Establish the source and the target job

Open the actual source file and report what you opened.

Record: title, author, edition, and format; rights to use the source; existing
skill or archive; target scope (personal, project, or plugin); intended users
and their expertise; prompts that should trigger the skill; outputs it must
produce; whether critique, teaching, creation, or all three are required; and
voice, policy, evidence, or formatting constraints.

Infer what the request and artifact make obvious. Ask only questions whose
answers would change architecture or safety.

Scope one skill per coherent user job — a job can draw on many chapters, and one
chapter can feed several runtime stages. Combine books only when they serve the
same job.

**Done when** every field above has a recorded value or an explicit "unknown",
and the target job is stated in one sentence.

### Phase 2 — Normalize and inventory the source

Read [references/source-extraction.md](references/source-extraction.md) for
format routing, the extraction-quality audit, and copyright rules.

Extract text to a working copy, leaving the original file untouched. For TXT or
Markdown:

```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/book_inventory.py" <source-file> --markdown
```

The inventory is navigation. Read the actual chapter bodies before drawing
conclusions, because qualifications and exceptions live in the prose rather than
the headings.

When extraction is defective enough to threaten fidelity, stop and name the exact
missing material.

**Done when** the source carries one of the reference's three quality verdicts
and every defect behind that verdict is named.

### Phase 3 — Build the source-method map

Use `assets/templates/SOURCE-METHOD-MAP.template.md`. The executable-unit
taxonomy — outcome, principle, decision rule, procedure, diagnostic,
transformation, template, playbook, exception, failure mode, evaluation
criterion — is defined in
[references/source-extraction.md](references/source-extraction.md), along with
the per-chapter review procedure.

Extract units rather than prose summaries, and classify each one:

- **Core runtime** — needed to perform the skill on an ordinary request.
- **Conditional reference** — needed for a genre, stage, or special case.
- **Test oracle** — useful mainly for evaluating behavior.
- **Context only** — interesting, not operational.
- **Exclude** — anecdote, repetition, obsolete detail, or copyrighted expression
  that does not improve execution. Record the reason.

**Done when** every substantive chapter has at least one extracted unit or a
recorded exclusion reason, with no chapter unaccounted for. In **map** mode,
deliver the completed map and stop here.

### Phase 4 — Define the behavior before writing the skill

Write five to twelve realistic user prompts covering ordinary requests, an
ambiguous or incomplete input, a difficult genre, a request that should be
declined or rerouted, an already-strong input that calls for **restraint**, and a
case where missing evidence must stay visible.

For each prompt define the intended artifact, the correct workflow or playbook,
the must-preserve facts, the required teaching, the forbidden behavior, and what
a clearly excellent output looks like.

Then fix the default response contract — the shape of the answer when the user
asks for nothing special.
[references/skill-architecture.md](references/skill-architecture.md) holds
contracts for teaching, creation, and analysis, plus the overrides that let a
user bypass them.

**Done when** all six fields are filled for every prompt and the default contract
is written down.

### Phase 5 — Design the architecture

Read [references/skill-architecture.md](references/skill-architecture.md) for the
runtime router, freedom levels, disclosure layout, and script criteria, and
[references/claude-skill-format.md](references/claude-skill-format.md) for
frontmatter, paths, structure, and size limits.

Use the smallest structure that preserves the method. Assign every Core runtime
unit to `SKILL.md`, every Conditional reference unit to a named reference file,
and every Test oracle unit to evals or regression tests.

**Done when** every unit on the map has an assigned destination file.

### Phase 6 — Write the executable skill

Write each method as a trigger chain:

```text
Trigger → Inspect → Decide → Act → Verify → Deliver
```

Convert weak knowledge statements —

> Strong openings are important.

— into executable instructions:

> Read the opening alone. If it does not reveal the reader's reason to continue,
> replace it with the request, recommendation, result, risk, or value.

Every method carries its exception, so **restraint** survives compression: state
when the rule stops applying and what to do instead.

Guard the two binding rules where the model is most tempted to break them. Under
**provenance**: attribute claims, metrics, credentials, and examples to a source
or mark them invented; preserve the user's voice rather than adopting the book's
personality; label adaptations where an obsolete source prescription was
modernized. Under **restraint**: leave strong input alone.

Teach with synthetic examples that isolate one transferable move, written with
new facts, names, and wording. Keep the source book, its extracted text, and long
before/after passages out of every distributable artifact unless the rights
holder authorizes inclusion.

**Done when** every Core runtime unit is implemented at its assigned location as
a trigger chain with its exception attached.

### Phase 7 — Audit the build against the source

**Ship mode.** Draft mode skips this phase and relies on the smoke evals below.

Complete `assets/templates/QA-REPORT.template.md` and score with the rubric in
[references/qa-and-evaluation.md](references/qa-and-evaluation.md), which also
holds the coverage classes and release gates.

Audit in both directions: source → skill catches omission, skill → source catches
invented doctrine. A genre chapter must change structure, tests, or output; a
chapter that only changed the tone has not survived the conversion.

**Done when** the coverage map carries a verdict for every substantive chapter
and every major runtime rule has recorded provenance.

### Phase 8 — Build and run the tests

**Draft mode** needs only `evals/evals.json` with at least three smoke evals —
realistic prompts with verifiable expectations, enough to prove the skill
triggers and produces the artifact. **Ship mode** adds `REGRESSION-TESTS.md` and
the full suite below.

Create both from their templates in `assets/templates/`.
[references/qa-and-evaluation.md](references/qa-and-evaluation.md) gives the four
test layers and the fields each test needs;
[references/claude-skill-format.md](references/claude-skill-format.md) gives the
eval schema and the two questions evaluation answers.

Cover each core transformation and playbook; preservation of numbers, names,
dates, scope, and uncertainty; missing-information placeholders; unsafe or
wrong-channel requests; output-format overrides; already-strong input;
conflicting source guidance; and long or noisy input.

Give evaluators only the skill, the raw prompt, and the raw artifact, so the test
measures the skill rather than the hint. Test the models the user plans to use,
and record which models actually ran.

When independent testing is unavailable, say so in the QA report and run the
suite through direct artifact inspection.

**Done when** every high-risk test has been run and its actual result recorded.

### Phase 9 — Validate and package

```bash
python3 "${CLAUDE_SKILL_DIR}/scripts/validate_claude_skill.py" \
  <skill-directory> \
  --out <output-directory>/<skill-name>.zip
```

The validator is the single source of truth for name, frontmatter, link, eval,
script, and archive rules. Fix what it reports.

Then open the archive listing and read it. Report artifacts from that listing,
and delete the working extraction copy from Phase 2.

**Done when** the listing has been read and matches the deliverables below.

## Branches

**Improving an existing skill.** Run the same phases with the current skill as a
second source: Phase 3 maps the book, Phase 7 audits the skill against that map
in both directions. Preserve the existing directory name and frontmatter name.
Baseline new behavior against the original skill rather than against no skill.

**A library of books.** Read
[references/batch-workflow.md](references/batch-workflow.md) for the catalog,
grouping, pilot, and gate structure. Process one representative book end to end
and confirm the architecture generalizes before running the rest. Each source
earns its own method map and coverage audit — a title-level scan is **theatre**,
not coverage.

## Deliverables

**draft** returns the installable `<skill-name>.zip`, its smoke evals, and a short
coverage note. **ship** adds the QA report, the regression tests, the full
source-method coverage map, and a summary of design choices and limitations.

The ZIP extracts into `~/.claude/skills/` for personal use or `.claude/skills/`
for one project. Install only when asked.