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 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:

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, 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 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 for the runtime router, freedom levels, disclosure layout, and script criteria, and 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:

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, 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 gives the four test layers and the fields each test needs; 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

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 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.