craft-book
Books built here are for one named reader. Their purpose is transferable judgement,
not coverage: short enough to finish, correct enough to trust, and shaped by what the
reader already knows. The stateful artefacts are the learner profile
(~/.agents/books/learner-profile.md), a BOOK-BRIEF.md in the workspace, and the
book source itself.
Workflow
- Probe — follow INTAKE.md.
scripts/profile.py show first and only
probe the delta (reconfirm anything flagged stale). Interview one question at a time
with a recommended answer, run the short diagnostic, then write BOOK-BRIEF.md and
get it approved. Do not write chapters before the brief is approved.
- Scaffold — pick the pipeline with the rule in PIPELINES.md
(default Markdown-first), then
python3 ~/.agents/skills/craft-book/scripts/new_book.py --pipeline markdown --dest DIR --title "...".
The sample chapters show every supported construct; replace them, never start blank.
- Write — follow WRITING.md: the chapter anatomy, the conditions
rule, worked numbers, and the residue rule. Gather sources first; cite primary ones.
Write
checks/NN-topic.py for every number in a worked example or answer.
- Build and verify —
make builds and checks all requested editions;
make verify runs the numeric checks; make pages renders contact sheets. Then do
the visual and correctness passes in QA.md. Nothing ships on a green
checker alone: look at the pages.
- Deliver — hand over the requested files from
output/, a READING-PLAN.md
keyed to the reader's timeline, and record the book and its verified levels with
profile.py. Offer a Send-to-Kindle test and the self-test companion.
Quick start
python3 ~/.agents/skills/craft-book/scripts/new_book.py --pipeline markdown \
--dest my-book --title "The Probability Spine" --author "Prepared for Sam"
cd my-book && make && make verify && make pages
Non-negotiables
- One source, every edition. Never hand-edit an output file.
- Every identity states its conditions; every number has a check; no claim rests on
parametric memory alone when a primary source is available.
- Page budget is part of the brief (default 40–60 pages of 7×10 in). Cutting is the
writer's job, not the reader's.
- Callouts are the six defined classes only: mentalmodel, failuremode, checkpoint,
takeaway, example, algorithm. Answers to every checkpoint live in the back matter.
- The Kindle contract in PIPELINES.md is binding whenever EPUB is requested.
- Read every page render before delivery; fix what the checkers cannot see.
- The learner profile evolves itself: apply the triggers in PROFILE.md
through
scripts/profile.py (never by rewriting the file), silently, and honour
"leave my profile alone" for a task via CRAFT_BOOK_PROFILE=off.
Files
scripts/ — new_book.py scaffold; profile.py (learner-profile edits + log);
check_pdf.py, check_epub.py, check_markdown.py, polish_epub.py,
count_tables.py, contact_sheet.sh, run_checks.py (shared by both pipelines).templates/markdown-first/, templates/latex-first/ — complete, buildable sample books.templates/profile/learner-profile.md, templates/BOOK-BRIEF.md, templates/READING-PLAN.md.
1---2name: craft-book3description: Write a personalised technical book (field guide, course companion, prerequisite refresher, study spine) and ship it as a print PDF, a Kindle-ready EPUB, and portable Markdown from one source, after probing the reader's intent and verified skill level. Use when the user asks for a book, textbook, study guide, companion, refresher, field guide, "something I can read on my Kindle", or wants existing notes turned into a proper book; also for revising or re-exporting a book built with this skill.4---56# craft-book78Books built here are for one named reader. Their purpose is transferable judgement,9not coverage: short enough to finish, correct enough to trust, and shaped by what the10reader already knows. The stateful artefacts are the learner profile11(`~/.agents/books/learner-profile.md`), a `BOOK-BRIEF.md` in the workspace, and the12book source itself.1314## Workflow15161. **Probe** — follow [INTAKE.md](INTAKE.md). `scripts/profile.py show` first and only17 probe the delta (reconfirm anything flagged stale). Interview one question at a time18 with a recommended answer, run the short diagnostic, then write `BOOK-BRIEF.md` and19 get it approved. Do not write chapters before the brief is approved.202. **Scaffold** — pick the pipeline with the rule in [PIPELINES.md](PIPELINES.md)21 (default Markdown-first), then22 `python3 ~/.agents/skills/craft-book/scripts/new_book.py --pipeline markdown --dest DIR --title "..."`.23 The sample chapters show every supported construct; replace them, never start blank.243. **Write** — follow [WRITING.md](WRITING.md): the chapter anatomy, the conditions25 rule, worked numbers, and the residue rule. Gather sources first; cite primary ones.26 Write `checks/NN-topic.py` for every number in a worked example or answer.274. **Build and verify** — `make` builds and checks all requested editions;28 `make verify` runs the numeric checks; `make pages` renders contact sheets. Then do29 the visual and correctness passes in [QA.md](QA.md). Nothing ships on a green30 checker alone: look at the pages.315. **Deliver** — hand over the requested files from `output/`, a `READING-PLAN.md`32 keyed to the reader's timeline, and record the book and its verified levels with33 `profile.py`. Offer a Send-to-Kindle test and the self-test companion.3435## Quick start3637```sh38python3 ~/.agents/skills/craft-book/scripts/new_book.py --pipeline markdown \39 --dest my-book --title "The Probability Spine" --author "Prepared for Sam"40cd my-book && make && make verify && make pages41```4243## Non-negotiables4445- One source, every edition. Never hand-edit an output file.46- Every identity states its conditions; every number has a check; no claim rests on47 parametric memory alone when a primary source is available.48- Page budget is part of the brief (default 40–60 pages of 7×10 in). Cutting is the49 writer's job, not the reader's.50- Callouts are the six defined classes only: mentalmodel, failuremode, checkpoint,51 takeaway, example, algorithm. Answers to every checkpoint live in the back matter.52- The Kindle contract in [PIPELINES.md](PIPELINES.md) is binding whenever EPUB is requested.53- Read every page render before delivery; fix what the checkers cannot see.54- The learner profile evolves itself: apply the triggers in [PROFILE.md](PROFILE.md)55 through `scripts/profile.py` (never by rewriting the file), silently, and honour56 "leave my profile alone" for a task via `CRAFT_BOOK_PROFILE=off`.5758## Files5960- `scripts/` — `new_book.py` scaffold; `profile.py` (learner-profile edits + log);61 `check_pdf.py`, `check_epub.py`, `check_markdown.py`, `polish_epub.py`,62 `count_tables.py`, `contact_sheet.sh`, `run_checks.py` (shared by both pipelines).63- `templates/markdown-first/`, `templates/latex-first/` — complete, buildable sample books.64- `templates/profile/learner-profile.md`, `templates/BOOK-BRIEF.md`, `templates/READING-PLAN.md`.
abhinand5