# zhimaai/booktoskill architecture

> Architecture diagram of the GitHub repository zhimaai/booktoskill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhimaai/booktoskill
- Repository: https://github.com/zhimaai/booktoskill

## Overview

Book to Skill converts TXT, Markdown, DOCX, and PDF documents into an installable, evidence-grounded Skill ZIP, then provides bounded lexical retrieval in generated skills. The main workflow is conversion and asset extraction, heading-aware chunking, model-authored evidence metadata, validation and index merging, then packaging; at runtime, an agent searches the index and consults source Markdown or assets. The README documents the broader stages and optional OCR; sampled excerpts are partial, so some internal wiring is represented only where documented.

Main entry points: [`scripts/convert_documents.py`](https://github.com/zhimaai/booktoskill/blob/main/scripts/convert_documents.py) (Format conversion), [`scripts/prepare_workflow.py`](https://github.com/zhimaai/booktoskill/blob/main/scripts/prepare_workflow.py) (Workflow preparation), [`scripts/split_markdown.py`](https://github.com/zhimaai/booktoskill/blob/main/scripts/split_markdown.py) (Chunk manifest), [`scripts/batch_index.py`](https://github.com/zhimaai/booktoskill/blob/main/scripts/batch_index.py) (Batch iterator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Document preparation"]
  node_prepare["Workflow preparation"]
  node_converter["Format conversion"]
  node_markdown_assets["Markdown and assets"]
  node_splitter["Heading-aware chunking<br/>[split_markdown.py]"]
end

subgraph group_indexing["Evidence indexing"]
  node_chunk_manifest["Chunk manifest<br/>[split_markdown.py]"]
  node_batcher["Batch iterator<br/>[batch_index.py]"]
  node_batch_parts["Batch result files<br/>[batch_index.py]"]
  node_merger["Index validator and merger<br/>[merge_index.py]"]
  node_knowledge_index["Grounded JSONL index<br/>[merge_index.py]"]
end

subgraph group_package["Skill packaging"]
  node_skill_builder["Skill builder<br/>[build_skill.py]"]
  node_skill_zip["Installable Skill ZIP<br/>[build_skill.py]"]
end

subgraph group_runtime["Skill retrieval"]
  node_skill_instructions["Skill instructions<br/>[SKILL.md]"]
  node_agent_config["Agent metadata<br/>[openai.yaml]"]
  node_searcher["Bounded index search<br/>[search_index.py]"]
  node_source_markdown["Packaged source Markdown<br/>[build_skill.py]"]
  node_source_assets["Packaged source assets<br/>[build_skill.py]"]
end

node_operator(("Operator"))
node_source_docs["Source documents"]
node_ocr_service["ChatWiki parser"]
node_model_author(("Model batch author"))
node_agent(("Using agent"))

node_operator -->|"starts workflow"| node_prepare
node_source_docs -->|"provides files"| node_converter
node_prepare -->|"runs conversion"| node_converter
node_converter -->|"writes Markdown/assets"| node_markdown_assets
node_converter -.->|"requests OCR"| node_ocr_service
node_converter -->|"prepares documents"| node_splitter
node_splitter -->|"writes chunks"| node_chunk_manifest
node_prepare -->|"runs splitting"| node_splitter
node_chunk_manifest -->|"supplies chunks"| node_batcher
node_batcher -->|"presents bounded batch"| node_model_author
node_model_author -->|"writes results"| node_batch_parts
node_batcher -->|"reads completed parts"| node_batch_parts
node_batch_parts -->|"supplies results"| node_merger
node_chunk_manifest -->|"supplies evidence sources"| node_merger
node_merger -->|"validates and writes"| node_knowledge_index
node_knowledge_index -->|"supplies index"| node_skill_builder
node_markdown_assets -->|"supplies source files"| node_skill_builder
node_skill_builder -->|"packages skill"| node_skill_zip
node_skill_zip -->|"installs skill"| node_agent
node_agent -->|"submits query"| node_searcher
node_searcher -->|"reads and ranks"| node_knowledge_index
node_searcher -->|"returns candidates"| node_agent
node_agent -->|"opens referenced source"| node_source_markdown
node_agent -->|"inspects referenced assets"| node_source_assets
node_skill_instructions -->|"guides retrieval"| node_agent
node_agent_config -->|"provides metadata"| node_agent

click node_prepare "https://github.com/zhimaai/booktoskill/blob/main/scripts/prepare_workflow.py"
click node_converter "https://github.com/zhimaai/booktoskill/blob/main/scripts/convert_documents.py"
click node_markdown_assets "https://github.com/zhimaai/booktoskill/blob/main/scripts/convert_documents.py"
click node_splitter "https://github.com/zhimaai/booktoskill/blob/main/scripts/split_markdown.py"
click node_chunk_manifest "https://github.com/zhimaai/booktoskill/blob/main/scripts/split_markdown.py"
click node_batcher "https://github.com/zhimaai/booktoskill/blob/main/scripts/batch_index.py"
click node_batch_parts "https://github.com/zhimaai/booktoskill/blob/main/scripts/batch_index.py"
click node_merger "https://github.com/zhimaai/booktoskill/blob/main/scripts/merge_index.py"
click node_knowledge_index "https://github.com/zhimaai/booktoskill/blob/main/scripts/merge_index.py"
click node_skill_builder "https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py"
click node_skill_zip "https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py"
click node_skill_instructions "https://github.com/zhimaai/booktoskill/blob/main/SKILL.md"
click node_agent_config "https://github.com/zhimaai/booktoskill/blob/main/agents/openai.yaml"
click node_searcher "https://github.com/zhimaai/booktoskill/blob/main/scripts/search_index.py"
click node_source_markdown "https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py"
click node_source_assets "https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prepare,node_converter,node_markdown_assets,node_splitter toneBlue
class node_chunk_manifest,node_batcher,node_batch_parts,node_merger,node_knowledge_index toneAmber
class node_skill_builder,node_skill_zip toneMint
class node_skill_instructions,node_agent_config,node_searcher,node_source_markdown,node_source_assets toneRose
class node_operator,node_source_docs,node_ocr_service,node_model_author,node_agent toneIndigo
```

## Components

### Document preparation

- [Workflow preparation](https://github.com/zhimaai/booktoskill/blob/main/scripts/prepare_workflow.py): `scripts/prepare_workflow.py`
- [Format conversion](https://github.com/zhimaai/booktoskill/blob/main/scripts/convert_documents.py): `scripts/convert_documents.py`
- [Markdown and assets](https://github.com/zhimaai/booktoskill/blob/main/scripts/convert_documents.py): `scripts/convert_documents.py`
- [Heading-aware chunking](https://github.com/zhimaai/booktoskill/blob/main/scripts/split_markdown.py): `scripts/split_markdown.py`

### Evidence indexing

- [Chunk manifest](https://github.com/zhimaai/booktoskill/blob/main/scripts/split_markdown.py): `scripts/split_markdown.py`
- [Batch iterator](https://github.com/zhimaai/booktoskill/blob/main/scripts/batch_index.py): `scripts/batch_index.py`
- [Batch result files](https://github.com/zhimaai/booktoskill/blob/main/scripts/batch_index.py): `scripts/batch_index.py`
- [Index validator and merger](https://github.com/zhimaai/booktoskill/blob/main/scripts/merge_index.py): `scripts/merge_index.py`
- [Grounded JSONL index](https://github.com/zhimaai/booktoskill/blob/main/scripts/merge_index.py): `scripts/merge_index.py`

### Skill packaging

- [Skill builder](https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py): `scripts/build_skill.py`
- [Installable Skill ZIP](https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py): `scripts/build_skill.py`

### Skill retrieval

- [Skill instructions](https://github.com/zhimaai/booktoskill/blob/main/SKILL.md): `SKILL.md`
- [Agent metadata](https://github.com/zhimaai/booktoskill/blob/main/agents/openai.yaml): `agents/openai.yaml`
- [Bounded index search](https://github.com/zhimaai/booktoskill/blob/main/scripts/search_index.py): `scripts/search_index.py`
- [Packaged source Markdown](https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py): `scripts/build_skill.py`
- [Packaged source assets](https://github.com/zhimaai/booktoskill/blob/main/scripts/build_skill.py): `scripts/build_skill.py`

### Other components

- **Operator**
- **Source documents**
- **ChatWiki parser**
- **Model batch author**
- **Using agent**

## Connections

- Operator → Workflow preparation: starts workflow
- Source documents → Format conversion: provides files
- Workflow preparation → Format conversion: runs conversion
- Format conversion → Markdown and assets: writes Markdown/assets
- Format conversion → ChatWiki parser: requests OCR
- Format conversion → Heading-aware chunking: prepares documents
- Heading-aware chunking → Chunk manifest: writes chunks
- Workflow preparation → Heading-aware chunking: runs splitting
- Chunk manifest → Batch iterator: supplies chunks
- Batch iterator → Model batch author: presents bounded batch
- Model batch author → Batch result files: writes results
- Batch iterator → Batch result files: reads completed parts
- Batch result files → Index validator and merger: supplies results
- Chunk manifest → Index validator and merger: supplies evidence sources
- Index validator and merger → Grounded JSONL index: validates and writes
- Grounded JSONL index → Skill builder: supplies index
- Markdown and assets → Skill builder: supplies source files
- Skill builder → Installable Skill ZIP: packages skill
- Installable Skill ZIP → Using agent: installs skill
- Using agent → Bounded index search: submits query
- Bounded index search → Grounded JSONL index: reads and ranks
- Bounded index search → Using agent: returns candidates
- Using agent → Packaged source Markdown: opens referenced source
- Using agent → Packaged source assets: inspects referenced assets
- Skill instructions → Using agent: guides retrieval
- Agent metadata → Using agent: provides metadata