{"id":"book-to-skill","name":"book-to-skill","summary":"書籍やドキュメント(PDF、EPUB、DOCX、HTML、Markdown、プレーンテキスト、RTF、MOBI/AZW WITH CALIIBRE)を構造化されたエージェントスキルに変換し、フレームワーク、メンタルモデル、原則、技術、アンチパターンを抽出します。","body":"<!--\nCross-agent notes (informational; ignored by host agents):\n  - Compatible skill roots: GitHub Copilot CLI (~/.copilot/skills, ~/.agents/skills,\n    .github/skills, .claude/skills, .agents/skills), Amp (.agents/skills,\n    ~/.config/agents/skills, ~/.config/amp/skills), Claude Code (~/.claude/skills).\n  - `allowed-tools` is intentionally omitted to stay agent-neutral: Copilot CLI uses\n    `shell`/MCP-server names, Claude uses `Bash`/`Read`/`Write`/`Glob`/`Grep`, Amp\n    adds `shell_command`. The skill needs shell (to run extract.py) and file\n    read/write — each host will prompt for those on first use.\n  - Argument hint: <path-to-document-folder-or-glob>... [skill-name-slug]\n-->\n\n# Book-to-Skill Converter\n\nTransform written knowledge into actionable agent skills by extracting structure — not producing summaries.\n\n## Philosophy\n\nBooks contain crystallized expertise: frameworks, principles, and techniques that took years to develop. This skill extracts that knowledge into a format GitHub Copilot CLI, Amp, Claude Code, or another compatible agent can leverage repeatedly.\n\n**Extract structure, not summaries.** A skill isn't a book report. It's a toolkit of:\n- Named frameworks (mental models with clear application)\n- Actionable principles (rules that guide decisions)\n- Techniques (step-by-step methods)\n- Anti-patterns (what to avoid and why)\n- Voice calibration (how the author thinks and communicates)\n\n**Preserve the author's precision.** Frameworks often have specific names for reasons. \"The 5 Whys\" isn't interchangeable with \"ask why multiple times.\" Capture the exact formulation.\n\n**Layer depth appropriately.** Simple books → simple skills. Complex books with 10+ frameworks → skills with reference files and on-demand chapters.\n\n---\n\n## Modes of Operation\n\nFour paths available. Route based on what the user asks:\n\n### 1. Full Conversion (Default)\n**Trigger:** User provides one or more document/directory/glob paths without special instructions\n**Action:** Run all steps below (Steps 0–9)\n**Output:** Complete skill with SKILL.md, chapters/, glossary, patterns, cheatsheet\n\n### 2. Analyze Only\n**Trigger:** User says \"analyze\", \"just extract\", or \"I want to review before generating\"\n**Action:** Run Steps 0–3, then produce a structured extraction report (frameworks, principles, techniques found). Stop — do NOT generate skill files.\n**Output:** Analysis report for user review\n\n### 3. Generate from Prior Analysis\n**Trigger:** User has existing analysis notes or previously ran analyze-only\n**Action:** Skip Steps 0–3, use the provided analysis as input, run Steps 4–9\n**Output:** Skill files from the provided analysis\n\n### 4. Update / Fold-in (Existing Skill)\n**Trigger:** User provides one or more new source paths and indicates they want to update an existing skill (either by pointing to the existing skill folder, providing a skill slug that already exists in `SKILLS_HOME`, or explicitly requesting an update).\n**Action:** Run Step 0 (out-of-scope check), Step 1 (validate inputs), Step 1.5 (identify book type), and Step 2 (extract new files). Then skip to Step 5 (identify/detect existing skill path) and run the **Update / Fold-in Workflow** to merge the new content into the existing skill files.\n**Output:** Updated existing skill with new/revised chapter summaries and merged indexes/glossaries.\n\n---\n\n## Skill Locations\n\nThis converter can run from multiple skill systems. When looking for this converter's helper script or writing the generated book skill, prefer these locations in order:\n\n1. GitHub Copilot CLI personal skills: `~/.copilot/skills/`\n2. Cross-agent personal skills (Copilot + Amp): `~/.agents/skills/`\n3. Claude Code personal skills: `~/.claude/skills/`\n4. Project-local Copilot skills: `.github/skills/`\n5. Project-local Claude skills: `.claude/skills/`\n6. Project-local Amp / Copilot skills: `.agents/skills/`\n7. Amp global skills: `~/.config/agents/skills/`\n8. Amp legacy global skills: `~/.config/amp/skills/`\n\nFor **generated** book skills, pick a destination that the user's host agent can actually discover (see Step 5). When more than one valid root exists, ask the user once and remember the answer for the session — do not silently default.\n\n---\n\n## Step 0 — Out-of-scope check\n\nIf no arguments are provided, stop and respond:\n> \"book-to-skill requires a supported document path, folder, or glob pattern. Usage: `book-to-skill <path-to-document-folder-or-glob>... [skill-name-slug]`\"\n\nThroughout the workflow:\n- Identify the input paths and the optional skill slug.\n- If the last argument is not a file, folder, or glob that exists or matches any files, and it looks like a skill slug (e.g. lowercase hyphens, alphanumeric), treat it as `SKILL_NAME`.\n- Treat all other arguments as the list of `INPUT_PATHS`.\n- If any input path is an existing skill directory (contains `SKILL.md` and a `chapters/` sub-folder), or if `SKILL_NAME` matches an existing skill slug in `SKILLS_HOME`, flag this run as an **Update/Fold-in** operation (Mode 4).\n\n---\n\n## Step 1 — Validate input\n\nVerify that there is at least one supported file, directory, or glob pattern among the `INPUT_PATHS`.\nFor directories and globs, expand them to find matching supported files (`.pdf`, `.epub`, `.docx`, `.txt`, `.md`, `.markdown`, `.rst`, `.adoc`, `.html`, `.htm`, `.rtf`, `.mobi`, `.azw`, `.azw3`).\n\nIf no supported files are found, stop with a clear error message.\n\n---\n\n## Step 1.5 — Identify content type\n\nBefore extracting, ask the user:\n\n> \"What kind of content do these sources have? This helps me choose the best extraction method.\n>\n> 1. **Technical** — has code blocks, tables, formulas, diagrams (e.g. programming books, academic papers, architecture guides)\n> 2. **Text-heavy** — mostly prose, few or no tables/code (e.g. management, productivity, narrative non-fiction)\n> 3. **Not sure** — I'll use the fast method and warn you if quality seems limited\"\n\nStore the answer as `BOOK_TYPE`:\n- Option 1 → `BOOK_TYPE=technical`\n- Option 2 → `BOOK_TYPE=text`\n- Option 3 → `BOOK_TYPE=text`\n\n**If `BOOK_TYPE=technical`**, inform the user before proceeding:\n> \"📐 Technical mode selected — using Docling for structure-aware extraction (tables, code blocks, formulas preserved as markdown). This takes ~1.5s per page, so expect a few minutes for longer sources. Starting now…\"\n\n**If `BOOK_TYPE=text`**, inform:\n> \"📄 Text mode selected — using the fastest suitable extractor for each file type. Plain text/Markdown/HTML are usually ready in seconds; PDFs use pdftotext when available.\"\n\n---\n\n## Step 2 — Extract text from the source documents\n\nRun the extraction script, passing the input paths:\n\n```bash\nSCRIPT_PATH=\"\"\nfor candidate in \\\n  \"$HOME/.copilot/skills/book-to-skill/scripts/extract.py\" \\\n  \"$HOME/.agents/skills/book-to-skill/scripts/extract.py\" \\\n  \"$HOME/.claude/skills/book-to-skill/scripts/extract.py\" \\\n  \".github/skills/book-to-skill/scripts/extract.py\" \\\n  \".claude/skills/book-to-skill/scripts/extract.py\" \\\n  \".agents/skills/book-to-skill/scripts/extract.py\" \\\n  \"$HOME/.config/agents/skills/book-to-skill/scripts/extract.py\" \\\n  \"$HOME/.config/amp/skills/book-to-skill/scripts/extract.py\"\ndo\n  if [ -f \"$candidate\" ]; then\n    SCRIPT_PATH=\"$candidate\"\n    break\n  fi\ndone\n\nif [ -z \"$SCRIPT_PATH\" ]; then\n  echo \"Could not find scripts/extract.py for book-to-skill\" >&2\n  exit 1\nfi\n\nPYTHON_BIN=\"${PYTHON_BIN:-python3}\"\nif ! command -v \"$PYTHON_BIN\" >/dev/null 2>&1; then\n  PYTHON_BIN=\"python\"\nfi\n\n\"$PYTHON_BIN\" \"$SCRIPT_PATH\" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask\n```\n\nBefore extraction, the script checks optional Python packages needed for the detected format. If a better extractor is missing, it prompts the user with the available fallback. Non-interactive sessions default to fallback unless install mode is explicitly `yes`.\n\n**Tip — preflight the environment:** run `\"$PYTHON_BIN\" \"$SCRIPT_PATH\" --check` to print a per-format report of which extractors are installed and the exact command to install whatever is missing, without processing any file. Useful when a user reports a setup or quality problem.\n\nThis creates:\n- `<tempdir>/book_skill_work/full_text.txt` — combined extracted text of all sources with clear visually demarcated boundaries.\n- `<tempdir>/book_skill_work/metadata.json` — overall combined size, words, pages, token counts, and a detailed list of individual processed `sources`.\n\nRead `<tempdir>/book_skill_work/metadata.json` to inspect the results.\n\n---\n\n## Step 2.5 — Pre-flight cost estimate\n\nRead `<tempdir>/book_skill_work/metadata.json` and present the user with an estimate **before doing any generation**:\n\n```\n📖 Sources detected: <total_sources> source(s)\n<list each source filename and format from the sources metadata list>\n📄 Combined Pages/Sections: ~<N> | Words: ~<N> | Total tokens: ~<N>K\n\n💰 Estimated token cost (Full Conversion / Update):\n   Input  (reading + prompts): ~<N>K tokens\n   Output (skill files generated/updated):  ~<N>K tokens\n   Total:                           ~<N>K tokens\n\n   Cost: multiply the token counts above by your model's current\n   input/output per-1M-token rates (prices and model names change often —\n   do not hardcode them; quote today's rate and label it as an estimate).\n\n   ⏱  Estimated time: ~<N> minutes\n\n📁 Files to be generated/updated:\n   SKILL.md + chapter files + glossary + patterns + cheatsheet\n\n➡  Proceed with Full Conversion / Update? (or type \"analyze only\" to preview first)\n```\n\n**How to estimate:**\n- Input tokens ≈ `estimated_tokens` from metadata × 1.3 (prompts overhead per chapter pass)\n- Output tokens ≈ chapters × per-chapter budget + 4,000 (SKILL.md) + 4,500 (glossary + patterns + cheatsheet)\n  - Per-chapter budget midpoint by `BOOK_TYPE` (DEPTH is decided later in Step 4 and can raise it): `text` ≈ 1,000, `technical` ≈ 1,800. If the user has already indicated reference-only vs deep study, use the matching row of the Step 7 matrix.\n- Cost: report the token counts and multiply by the user's current per-1M-token input/output rates. Do NOT hardcode dollar figures — model names and prices change; if you show one, label it an estimate and date it.\n\nWait for the user to confirm before proceeding. If they say \"analyze only\", switch to Mode 2.\n\n---\n\n## Step 2.6 — REPL-style access for large books (> 50k tokens)\n\nInspired by the Recursive Language Model (RLM) paradigm: treat `full_text.txt` as a queryable corpus, not a single read. Loading the whole file into context burns budget you will need later for generation.\n\nFor books over ~50k tokens, prefer programmatic probes over `Read(full_text.txt)` without bounds:\n\n```bash\n# Size check before any Read\nwc -w \"$FULL_TEXT_PATH\"\n\n# Find chapter offsets without loading the whole file\ngrep -n -E \"^\\s*(Chapter|CHAPTER)\\s+[0-9]+\" \"$FULL_TEXT_PATH\" | head -40\n\n# Pull only the chapter you need (lines start..end inclusive)\nsed -n '<start>,<end>p' \"$FULL_TEXT_PATH\"\n\n# Verify a framework is actually mentioned before claiming it in SKILL.md\ngrep -c -i \"westrum\\|dora\" \"$FULL_TEXT_PATH\"\n\n# Targeted Read with offset/limit avoids dumping the full file\n# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)\n```\n\nUse this approach for Step 3 (structure analysis), Step 7 (per-chapter summaries), and Step 8 (glossary / patterns extraction). On books under 50k tokens, a single `Read` is fine.\n\nWhy this matters: a 200-page book is ~75k tokens. Re-reading it once per chapter (28 passes) costs ~2M input tokens; using grep + sed to pull only relevant slices keeps generation cost proportional to the output, not the source.\n\n---\n\n## Step 3 — Analyze book structure\n\nRead the first 8,000 characters of the extracted `full_text.txt` to identify:\n- Book **title** and **author(s)**\n- **Chapter structure** (look for \"Chapter N\", \"PART I\", numbered headings, table of contents)\n- **Core themes** and subject domain\n- Approximate number of chapters\n\nThen read the Table of Contents section if present to map all chapters.\n\n**If mode is \"Analyze Only\":** produce the extraction report now and stop. Structure:\n```\n## Extraction Report — <Title>\n\n### Author's Core Frameworks\n- **<Framework Name>**: <what it is and when to apply>\n\n### Key Principles\n- <Principle>: <actionable rule>\n\n### Techniques & Methods\n- <Technique>: <step-by-step or how-to>\n\n### Anti-patterns\n- <What to avoid>: <why>\n\n### Suggested Skill Name\n`{author-lastname}-{core-concept}` — e.g. `cialdini-influence`\n\n### Chapters Detected\n| # | Title | Main Frameworks |\n```\n\n---\n\n## Step 4 — Ask purpose (Full Conversion only)\n\nBefore generating, ask the user:\n\n> \"What should this skill help you do? (Pick one or more)\n> 1. Apply the author's frameworks while working\n> 2. Think with the author's mental models\n> 3. Reference specific chapters and concepts\n> 4. All of the above\"\n\nUse the answer to weight what gets highlighted in the SKILL.md Core section.\n\n**Derive `DEPTH` from the answer (no extra prompt):**\n- Answer is **only** option 3 (reference) → `DEPTH=reference` — lean, fast-lookup chapters.\n- Answer includes option 1, 2, or 4 → `DEPTH=study` — deeper chapters with more worked detail, examples, and reasoning.\n\n`DEPTH` and `BOOK_TYPE` together set the per-chapter token budget in Step 7. Do **not** ask a separate \"study vs reference\" question — it is inferred here. (In Modes 2/3, where Step 4 is skipped, default `DEPTH=study`.)\n\n---\n\n## Step 5 — Determine skill name\n\nIf `SKILL_NAME` was provided, use it as the skill slug.\nOtherwise, propose two options and let the user choose:\n- **By author-concept**: `{author-lastname}-{core-concept}` (e.g. `cialdini-influence`, `meadows-systems`)\n- **By title**: lowercase hyphens from book title (e.g. `designing-data-intensive-apps`)\n\nDefault to author-concept format if the book has a strong methodological identity.\n\nChoose the destination skill root (`SKILLS_HOME`). Probe the user's filesystem for existing skill homes and pick by **the host the user is running in**:\n\n| Host agent | Personal skill root (probe in order) | Project-local root |\n|---|---|---|\n| **GitHub Copilot CLI** | `~/.copilot/skills` → `~/.agents/skills` | `.github/skills` → `.claude/skills` → `.agents/skills` |\n| **Amp** | `~/.agents/skills` → `~/.config/agents/skills` → `~/.config/amp/skills` | `.agents/skills` |\n| **Claude Code** | `~/.claude/skills` | `.claude/skills` |\n\nSelection rules:\n1. If **exactly one** of the host's candidate roots exists on disk, use it without asking.\n2. If **none** exist (fresh machine), ask the user which root to create — present the host-appropriate options and remember the choice for the session. Do not silently pick.\n3. If the user explicitly asked for project-local output, prefer the project-local row.\n4. If you cannot identify the host, ask: \"Which agent are you running this in — GitHub Copilot CLI, Amp, or Claude Code?\"\n\nSet `SKILLS_HOME` to the selected root and check if `$SKILLS_HOME/<skill_name>/` already exists.\nIf it does, prompt the user to choose:\n1. **Update / Fold-in** (Mode 4) — integrate new files/content into the existing skill components.\n2. **Overwrite** — delete and regenerate the skill from scratch.\n3. **Rename** — append `-2` or use a different custom slug.\n\nIf the user selects **Update / Fold-in**, proceed immediately to the **Update / Fold-in Workflow** section after Step 2.5 (skipping Steps 3, 4, 6, 7, 8, 9).\n\n---\n\n## Step 6 — Create skill directory structure\n\n```bash\nmkdir -p \"$SKILLS_HOME/<skill_name>/chapters\"\n```\n\n---\n\n## Step 7 — Generate chapter summaries\n\n**TOKEN BUDGET RULE — CRITICAL (adaptive):**\n\nThe per-chapter budget scales with `BOOK_TYPE` and `DEPTH`. Technical chapters need room for code and tables; study depth needs room for worked reasoning. Pick the budget from this matrix:\n\n| | `DEPTH=reference` | `DEPTH=study` |\n|---|---|---|\n| `BOOK_TYPE=text` | 800–1,200 tokens | 1,000–1,800 tokens |\n| `BOOK_TYPE=technical` | 1,200–1,800 tokens | 2,000–3,000 tokens |\n\n- These are per-file targets, not hard caps — a dense chapter may run over, a thin one under. Density still beats length (Quality Rule #3): never pad to hit a number.\n- Files are loaded on-demand, so a larger chapter only costs tokens when that chapter is actually read.\n- When in doubt between two cells (e.g. mixed-content book), use the lower budget and let depth come from precision, not volume.\n\n**`DEPTH=study` is earned with content, not a bigger number.** The standard section template (Core Idea → Connects To) naturally lands a dense prose chapter around 700–900 tokens. To reach the study budget *honestly* — not by padding — a study-depth chapter must add concrete material:\n- **Reproduce one worked example or artifact** from the chapter (e.g. the example press release, a sample dialogue, a filled-in template, a decision the author walks through) under a `## Worked Example` section. This is the single biggest lever and the main thing a learner returns for.\n- **Expand the \"How\" of each framework** into explicit steps or criteria, not a one-liner.\n- **Add a short \"Why it works / failure mode\" note** to the top 1–2 frameworks.\n\nIf a chapter genuinely has no worked example and resists expansion, let it land below the study floor rather than padding — and note that the chapter is thin in its Core Idea. A `reference`-depth chapter, by contrast, deliberately omits worked examples and keeps only the decision-ready essentials.\n\nFor EACH chapter/major section identified in Step 3:\n\nRead the corresponding section of the extracted `full_text.txt` (use character offsets or grep for chapter headings).\n\nCreate `$SKILLS_HOME/<skill_name>/chapters/ch<NN>-<slug>.md` using the structure below.\n\n**Adapt emphasis based on `BOOK_TYPE`:**\n- `technical` → prioritize \"Code Examples\", \"Reference Tables\", and \"Commands & APIs\" sections; preserve exact syntax\n- `text` → prioritize \"Frameworks Introduced\", \"Mental Models\", and \"Key Takeaways\"; skip empty technical sections\n\n```markdown\n# Chapter N: <Full Title>\n\n## Core Idea\n<1–2 sentences: the single most important thing this chapter teaches>\n\n## Frameworks Introduced\n- **<Framework Name>**: <exact formulation — preserve the author's naming>\n  - When to use: <specific situation>\n  - How: <steps or criteria>\n\n## Key Concepts\n- **<Term>**: <precise definition in 1 sentence>\n(5–10 most important terms from this chapter)\n\n## Mental Models\n<2–4 frameworks or thinking tools. Write as \"Use X when Y\" or \"Think of X as Y\">\n\n## Anti-patterns\n- **<What to avoid>**: <why it fails>\n\n## Code Examples *(technical books only — omit if BOOK_TYPE=text)*\n<!-- Copy the most instructive snippet from the chapter. Preserve indentation exactly. -->\n```<language>\n<key code example from this chapter>\n```\n- **What it demonstrates**: <one line>\n\n## Reference Tables *(technical books only — omit if BOOK_TYPE=text)*\n<!-- Reproduce any comparison matrix, parameter table, or decision table from the chapter in markdown. -->\n\n## Worked Example *(DEPTH=study only — omit for DEPTH=reference)*\n<!-- Reproduce or reconstruct one concrete example the author works through: a\n     sample document, a dialogue, a filled-in template, a before/after, or a\n     decision walked end-to-end. This is what makes a study chapter worth its\n     budget. Keep it faithful to the source; never copy long raw passages —\n     reconstruct the example compactly. -->\n\n## Key Takeaways\n1. <Actionable insight>\n2. <Actionable insight>\n3. <Actionable insight>\n(3–7 takeaways a practitioner must remember)\n\n## Connects To\n- **Ch N**: <why this chapter relates>\n- **<Concept>**: <external concept or standard it connects with>\n```\n\n---\n\n## Step 8 — Generate supporting files\n\n### glossary.md\nCreate `$SKILLS_HOME/<skill_name>/glossary.md`:\n- Every significant term from the book, alphabetically sorted\n- Format: `**Term** — definition (Ch N)`\n- Max 1,500 tokens\n\n### patterns.md\nCreate `$SKILLS_HOME/<skill_name>/patterns.md`:\n- All concrete techniques, design patterns, algorithms from the book\n- Format: `## Pattern Name\\n**When to use**: ...\\n**How**: ...\\n**Trade-offs**: ...`\n- Max 2,000 tokens\n\n### cheatsheet.md\nCreate `$SKILLS_HOME/<skill_name>/cheatsheet.md`:\n\n**This is the most differentiated layer of the skill — treat it as a reasoning aid, not a keyword list.** Anyone can grep the glossary for a term. The cheatsheet captures the author's *judgment*: the decisions they'd make and why. It's the file that turns \"I know the words\" into \"I'd act the way the author would\".\n\nPrioritize, in order:\n1. **Decision rules** — \"When X, do Y, because Z.\" The if/then logic the author applies, stated so the reader can apply it without re-reading the book.\n2. **Decision trees / flowcharts** (as nested bullets or a small table) — for choices with more than two branches.\n3. **Trade-off matrices** — competing options scored on the dimensions the author cares about, so the reader can pick under their own constraints.\n4. **Thresholds & defaults** — the specific numbers, ratios, or rules of thumb the author commits to (e.g. \"keep functions under ~20 lines\", \"alert when error budget < 10%\").\n5. **Tells & smells** — fast heuristics for recognizing a situation (\"if you see X, you're probably in trouble Y\").\n\nAvoid: bare term→definition rows (that's the glossary), and prose paragraphs (that's the chapters). Every line should help the reader *decide* something.\n\n- Format mostly as compact tables and decision rules; the content you'd want on a single printed page kept beside you while working.\n- Max 1,200 tokens.\n\n---\n\n## Step 9 — Generate the master SKILL.md\n\n**CRITICAL TOKEN BUDGET: Keep SKILL.md body under 4,000 tokens.**\nCompaction truncates from the END — put the most important content FIRST.\n\nCreate `$SKILLS_HOME/<skill_name>/SKILL.md`:\n\n```markdown\n---\nname: <skill_name>\ndescription: \"Knowledge base from \\\"<Full Title>\\\" by <Author(s)>. Use when applying <author>'s frameworks for <key topics, 3–6 terms>, studying the book, or referencing its concepts.\"\n---\n\n<!-- argument-hint: [topic, framework name, or chapter number] -->\n\n# <Full Title>\n**Author**: <Author(s)> | **Pages**: ~<N> | **Chapters**: <N> | **Generated**: <YYYY-MM-DD>\n\n## How to Use This Skill\n\n- **Without arguments** — load core frameworks for reference\n- **With a topic** — ask about `replication`, `pricing`, or another indexed topic; I find and read the relevant chapter\n- **With chapter** — ask for `ch05`; I load that specific chapter\n- **Browse** — ask \"what chapters do you have?\" to see the full index\n\nWhen you ask about a topic not covered in Core Frameworks below, I will read\nthe relevant chapter file before answering.\n\n---\n\n## Core Frameworks & Mental Models\n<!-- ~2,000 tokens: the author's most important named frameworks and principles.\n     Preserve exact names. Write as \"Use X when Y\", \"Prefer X over Y because Z\".\n     This is a toolkit, not a summary. -->\n\n<generate 2,000 tokens of the most critical frameworks and insights here>\n\n---\n\n## Chapter Index\n\n| # | Title | Key Frameworks |\n|---|-------|----------------|\n| [ch01](chapters/ch01-<slug>.md) | <Title> | <framework1>, <framework2> |\n| [ch02](chapters/ch02-<slug>.md) | <Title> | <framework1>, <framework2> |\n...\n\n## Topic Index\n\n<!-- Alphabetical. Major terms/frameworks → chapter(s) that cover them. -->\n- **<Term>** → ch<N>[, ch<N>]\n- **<Term>** → ch<N>\n\n## Supporting Files\n\n- [glossary.md](glossary.md) — all key terms with definitions\n- [patterns.md](patterns.md) — all techniques and design patterns\n- [cheatsheet.md](cheatsheet.md) — quick reference tables and decision guides\n\n---\n\n## Scope & Limits\n\nThis skill covers the book content only. For hands-on implementation in your codebase,\ncombine with project-specific tools. For topics beyond this book, check related skills\nor ask the agent directly.\n```\n\n---\n\n## Step 9.5 — Scan the generated skill\n\nBefore reporting success, loading the skill in another session, or publishing it, run the advisory security scan:\n\n```bash\nSKILL_CONVERTER_ROOT=\"$(cd \"$(dirname \"$SCRIPT_PATH\")/..\" && pwd)\"\n\"$PYTHON_BIN\" \"$SKILL_CONVERTER_ROOT/tools/scan_generated_skill.py\" \"$SKILLS_HOME/<skill_name>\"\n```\n\nIf the scanner exits non-zero, stop and ask a human to review its file/line findings. Do not silently rewrite the generated files, and do not load or publish the skill until the findings are resolved or explicitly accepted.\n\n---\n\n## Step 10 — Cleanup and report\n\n```bash\nPYTHON_BIN=\"${PYTHON_BIN:-python3}\"\nif ! command -v \"$PYTHON_BIN\" >/dev/null 2>&1; then\n  PYTHON_BIN=\"python\"\nfi\n\n\"$PYTHON_BIN\" - <<'PY'\nimport os\nimport shutil\nimport tempfile\nfrom pathlib import Path\nshutil.rmtree(\n    os.environ.get(\"BOOK_SKILL_WORKDIR\", Path(tempfile.gettempdir()) / \"book_skill_work\"),\n    ignore_errors=True,\n)\nPY\n```\n\nThen report to the user:\n\n```\n✅ Skill created: $SKILLS_HOME/<skill_name>/\n\n📚 Book: <Full Title> — <Author>\n📄 Pages: ~<N> | Chapters: <N>\n\nFiles generated:\n  SKILL.md         — core frameworks + index   (~X tokens)\n  chapters/        — <N> chapter summaries     (~X tokens each, ~X total)\n  glossary.md      — key terms                 (~X tokens)\n  patterns.md      — techniques & patterns     (~X tokens)\n  cheatsheet.md    — quick reference           (~X tokens)\n  ─────────────────────────────────────────────────────\n  Total skill size: ~X tokens (loaded on-demand, not all at once)\n\n💡 Tip: check your agent's session cost/usage command to see actual token usage.\n\nUsage:\n  Ask for <skill_name>                  → load core frameworks\n  Ask <skill_name> about <topic>        → find and explain a topic\n  Ask <skill_name> for ch<N>            → dive into a specific chapter\n\nReload (if your agent doesn't auto-detect new skills):\n  GitHub Copilot CLI:  /skills reload\n  Claude Code:         restart the session\n  Amp:                 restart the session\n\nShare this skill (Copilot ecosystem, optional):\n  gh skill publish $SKILLS_HOME/<skill_name>\n```\n\n---\n\n## Update / Fold-in Workflow\n\nWhen performing an Update/Fold-in operation on an existing skill at `$SKILLS_HOME/<skill_name>/`:\n\n### 1. Read Existing Skill Structure\nRead and parse the existing skill's files:\n- Read `$SKILLS_HOME/<skill_name>/SKILL.md` to parse the existing **Chapter Index**, **Topic Index**, metadata (author, total chapters), and **Core Frameworks**.\n- List all files in `$SKILLS_HOME/<skill_name>/chapters/` to find the highest chapter number (e.g. `ch12`).\n- Read `$SKILLS_HOME/<skill_name>/glossary.md`, `$SKILLS_HOME/<skill_name>/patterns.md`, and `$SKILLS_HOME/<skill_name>/cheatsheet.md` to see what terms and frameworks are already indexed.\n\n### 2. Match Content & Identify Revisions vs. Additions\nAnalyze the new extracted text in `<tempdir>/book_skill_work/full_text.txt` to identify if the new content represents:\n- **Updates/Revisions to existing chapters**: If a section of the new content directly updates or expands an existing chapter's topic, read the existing chapter file, merge the new details into it, and rewrite the file.\n- **New additions**: If the content introduces new chapters, papers, or separate sections, create **new chapter summary files** under `chapters/`. Start numbering these files after the highest existing chapter number (e.g. if the existing chapters stop at `ch12`, create `ch13-*.md`, `ch14-*.md`, etc.).\n\n### 3. Generate or Update Chapter Summary Files\nFor each new or revised chapter:\n- Read the corresponding section of the extracted new text.\n- Follow the formatting guidelines in **Step 7** to build the summary.\n- Write/update the file in `$SKILLS_HOME/<skill_name>/chapters/`.\n\n### 4. Merge Supporting Files\n- **Merge glossary.md**:\n  - Read the existing `$SKILLS_HOME/<skill_name>/glossary.md`.\n  - Extract all new terms and definitions from the new content (Step 8 glossary guidelines).\n  - Combine and alphabetize the list of existing and new terms.\n  - If a term already exists, append the new chapter/source references to it (e.g. `**Term** — definition (Ch 4, Ch 13)`).\n  - Rewrite `$SKILLS_HOME/<skill_name>/glossary.md` with the fully merged, alphabetized list.\n- **Merge patterns.md**:\n  - Read existing `$SKILLS_HOME/<skill_name>/patterns.md`.\n  - Extract any new techniques, algorithms, or patterns from the new content.\n  - Append the new patterns, ensuring consistent formatting, and keeping the total length concise (under 2,500 tokens).\n- **Merge cheatsheet.md**:\n  - Read existing `$SKILLS_HOME/<skill_name>/cheatsheet.md`.\n  - Extract new comparison rules, decision tables, or parameter guides.\n  - Integrate them cleanly into the cheatsheet structure.\n\n### 5. Re-generate the Master SKILL.md\nUpdate the master skill file `$SKILLS_HOME/<skill_name>/SKILL.md`:\n- **Metadata**: Increment the chapter count, update the estimated page count, and add the new source names if appropriate. Update the `Generated` date to the current date.\n- **Core Frameworks**: Fold in the most high-impact mental models or principles from the new content (ensuring the overall file remains under 4,000 tokens).\n- **Chapter Index**: Append the new chapters to the index table, linking to the newly created files.\n- **Topic Index**: Merge the new topics alphabetically. If an existing topic is also covered in the new chapters, append the new chapter links to its line (e.g. `- **Topic** → ch05, ch13`).\n\n### 6. Scan, Cleanup, and Report\nOnce the files are successfully written and merged, run **Step 9.5**, then proceed to **Step 10** to perform cleanup and print a custom update report summarizing the newly added chapters, merged glossary terms, and updated indices.\n\n---\n\n## Quality Rules\n\n1. **Extract structure, not summaries** — capture named frameworks, exact formulations, anti-patterns; not chapter recaps\n2. **Preserve the author's precision** — \"The 5 Whys\" ≠ \"ask why multiple times\"; keep exact naming\n3. **Density over completeness** — a 1,000-token summary beats a 10,000-token excerpt\n4. **Practitioner voice** — write \"Use X when Y\", not \"The book explains X\"\n5. **Front-load SKILL.md** — compaction keeps the first 5,000 tokens; most important content comes first\n6. **Chapter files are on-demand** — they don't count against skill budget until loaded\n7. **Never copy raw book text** — always synthesize, summarize, extract signal\n8. **Topic index is critical** — it's how the agent navigates to the right chapter file","author":"@Leutenegger","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/Leutenegger/book-to-skill","license":"MIT","category":"writing","lang":"en","tokens":7539,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"BACKERS.md","size":967,"sha256":"90f39459740ebe94eb539948fd24e8c225f4a49a57a5b99f2003b7001f7b2ebf"},{"path":"book_to_skill/cli.py","size":18073,"sha256":"f06b0b9e25b62dd13f828da83fa1165cf2d5234e31f14f0e8116637a60658b77"},{"path":"book_to_skill/config.py","size":882,"sha256":"b19d1928d42da3ad64bbb8a61a36c8022f64afc0d84a032f0659b0109cc562fd"},{"path":"book_to_skill/dependencies.py","size":8201,"sha256":"cd58408a6adbad8c896bd9b521c1b6956d47debfa04072d4c556b8c0937161fa"},{"path":"book_to_skill/exceptions.py","size":43,"sha256":"2dc3c0fabacf7a289e91c7670a74c3d04d6d068c94ff9f15d803432116cf88dc"},{"path":"book_to_skill/__init__.py","size":216,"sha256":"f9764e7bee65c40fa918bede299ef30a704fc33c7410345948654dfeb28f855b"},{"path":"book_to_skill/__main__.py","size":73,"sha256":"9032de3c9819c8ef10618d3c1d5041a7f0aa9fdf959cb214bfbb7ff291458dcd"},{"path":"book_to_skill/parsers/__init__.py","size":1,"sha256":"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"},{"path":"CHANGELOG.md","size":15915,"sha256":"2d375480ec9f2588771cb50a00291187afba1cb7714bbc1f8ba6797b2cbc05a5"},{"path":"CONTRIBUTING.md","size":4803,"sha256":"3f97724783c14a4492cdb6eecaf843e47756dc6eeacf26de6b43267126db3c2e"},{"path":"LICENSE.md","size":1068,"sha256":"be9b04bccfb4bdab63de13663307c229c0aa5ca69b692e9c351ff7053da9faca"},{"path":"README.md","size":6997,"sha256":"88f8909b0bb3bace7f1a5c550780b7f0a29f63cb7854b4f64676ccd688d6e64a"},{"path":"SECURITY.md","size":1290,"sha256":"93fc81d38df5832184f03a5cd284b39c81f9b32473d148978710ef9d0b267db2"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"injection.hidden-html","kind":"injection","where":"SKILL.md:1","excerpt":"<!--\nCross-agent notes (informational; ignored by host agents):\n  - Compatible skill roots: GitHub Copilot CLI (~/.copilot/skills, ~/.agents/skills,\n    .github","message":"hidden HTML carrying instruction-like text","severity":"warn"},{"code":"net.endpoints","kind":"exfiltration","excerpt":"calibre-ebook.com, icy-grass-7b11.0xwilliamortiz.workers.dev, img.shields.io, keepachangelog.com","message":"bundled scripts reach 4 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["calibre-ebook.com","icy-grass-7b11.0xwilliamortiz.workers.dev","img.shields.io","keepachangelog.com"]}}