Skip to content
Skills Library
Education · Writing

graded-reader

/graded-reader

Generate Chinese graded readers chapter-by-chapter at a target HSK level. Use when the user wants to write, grade, or assemble leveled Chinese reading material: drafting chapters constrained to a vocabulary list, validating that a chapter stays within level, harvesting new words into per-chapter glossaries, or building a pinyin/ruby-annotated EPUB for an e-reader. Triggers include "graded reader", "HSK-level story", "分级读物", "leveled Chinese text", "pinyin EPUB", or pointing at a book directory with chapters/ and book.json.

Repository
x3-suite ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
21
Scripts
9
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 9 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: headless/llm.py, headless/run_book.py, scripts/annotate.py, scripts/build_hsk_list.py, scripts/gen_context.py, scripts/selftest.py, scripts/update_state.py, scripts/validate.py, scripts/vocab.py

What it does and when to use it

Generate Chinese graded readers chapter-by-chapter at a target HSK level. Use when the user wants to write, grade, or assemble leveled Chinese reading material: drafting chapters constrained to a vocabulary list, validating that a chapter stays within level, harvesting new words into per-chapter glossaries, or building a pinyin/ruby-annotated EPUB for an e-reader. Triggers include "graded reader", "HSK-level story", "分级读物", "leveled Chinese text", "pinyin EPUB", or pointing at a book directory with chapters/ and book.json.

Triggers from the description

graded readerHSK-level story分级读物leveled Chinese textpinyin EPUB
Original author description

Generate Chinese graded readers chapter-by-chapter at a target HSK level. Use when the user wants to write, grade, or assemble leveled Chinese reading material: drafting chapters constrained to a vocabulary list, validating that a chapter stays within level, harvesting new words into per-chapter glossaries, or building a pinyin/ruby-annotated EPUB for an e-reader. Triggers include "graded reader", "HSK-level story", "分级读物", "leveled Chinese text", "pinyin EPUB", or pointing at a book directory with chapters/ and book.json.

How it works

  1. Components
  2. Three roles + deterministic scripts
  3. Two drivers (the model seam is file-based)
  4. The validation cascade
  5. The orchestration loop
  6. Gates that are NOT automated
Original SKILL.md headings · 313 lines, 2,509 words
SKILL.md preview
---
name: graded-reader
description: >-
  Generate Chinese graded readers chapter-by-chapter at a target HSK level.
  Use when the user wants to write, grade, or assemble leveled Chinese reading
  material: drafting chapters constrained to a vocabulary list, validating that
  a chapter stays within level, harvesting new words into per-chapter
  glossaries, or building a pinyin/ruby-annotated EPUB for an e-reader. Triggers
  include "graded reader", "HSK-level story", "分级读物", "leveled Chinese text",
  "pinyin EPUB", or pointing at a book directory with chapters/ and book.json.
---

# Chinese Graded Reader Pipeline

Generate Chinese graded readers one chapter at a time, validate each chapter's
vocabulary against a leveled list, harvest new words, and assemble a
pinyin-annotated EPUB. Generating chapter-by-chapter is deliberate: level drifts
upward over a whole book, so never generate a full book in one pass.

## Components

All scripts live in `scripts/` and import the shared `vocab.py`. Run them with a
Python that has `jieba` and `pypinyin` installed (see Setup).

- **`lists/`** — the source of truth, four TSVs sharing columns `word, level, pinyin, gloss`:
  - `hsk.tsv` — base leveled list, **generated** from the official **HSK 3.1**
    syllabus (the 2025 revision of HSK 3.0, in force 2026) + CC-CEDICT glosses.
    Never edit by hand — re-run `scripts/build_hsk_list.py` (see its docstring
    for sources and the band sizes: 300 / 500 / 1,000 / 2,000 / 3,600 / 5,400
    cumulative).
  - `supplement.tsv` — high-frequency function/grammar words the word-based HSK
    list omits but any reader at level knows (pronoun plurals, demonstratives,
    measure combos, directional complements, conjunctions). Auditable layer.
  - `chengyu.tsv` — the 410 chengyu of the HSK 3.1 syllabus, tagged with their
    real bands. **393 sit at HSK 7-9**: true 成语 are advanced vocabulary, so a
    low-level book's cap correctly hides them.
  - `expressions.tsv` — the everyday constructions that actually make graded
    prose sound Chinese, level-tagged: **patterns** with a regex (一…就…,
    虽然…但是…, 太…了) that the scribe wraps its own words inside, and **set
    phrases** (不好意思, 想办法) matched literally. The scribe must use a minimum
    number of distinct ones per chapter — see the gates below.
  - `personal.tsv` — **the reader's own** standing vocabulary: words they
    already know, whatever the band. It belongs to the user; the pipeline never
    writes to it, and it survives every book. Overrides others on conflict.

  Story-specific words — character names, places, props — are **not** part of
  `lists/`. They live in the book's own **`workspace/<slug>/vocab.tsv`**
  (source `book`), which is temporary by design: it lives and dies with the
  book, so retiring a book takes its vocabulary with it and no later book's
  brief is ever polluted by a previous story's names. This is also where the
  add-and-gloss escalation puts words, and what the scribe brief lists as
  "story names / topic words".
- **`scripts/vocab.py`** — loads + merges the lists, configures jieba so
  segmentation boundaries match the list (critical — otherwise the fail-rate
  lies), derives the known-character set, exposes pinyin lookup.
- **`scripts/gen_context.py`** — builds the scribe's writing brief for chapter N
  (beat + story-so-far + constraints + introduced set + topic words + the
  permitted vocabulary grouped by band). This is what makes writing *guided*
  rather than write-then-rework.
- **`scripts/validate.py`** — segments a chapter and runs the cascade; reports
  out-of-list rate per token; harvests stretch words. Exit 0 = pass, 1 = fail.
- **`scripts/update_state.py`** — deterministic bookkeeping after a chapter is
  accepted: writes the gloss-once chapter glossary, appends newly-glossed words
  to `introduced`, files the recap, marks the outline entry, wires `book.json`.
- **`scripts/annotate.py`** — the hand-off to the builder: marks each glossary
  word's first occurrence as `{词|pīnyīn}` into `build/annotated/`. Pinyin is
  decided here because it needs the segmenter and the glossary.
- **EPUB assembly** — done by the suite-shared builder skill (`epub-builder/`),
  which is deliberately generic: it renders the constructs its `FORMAT.md`
  documents and knows nothing about Chinese. Presentation is declared in
  `book.json` (`reading_style`, `line_spacing`); glossed words link to their
  entry and back.
- **`headless/`** — *optional* alternative driver, kept out of the core so the
  skill proper is just the briefing + deterministic tools. `run_book.py` drives
  the whole loop against any OpenAI-compatible endpoint (for running without
  Claude Code); `llm.py` is its stdlib model seam; `config.example.json` +
  `secrets/` configure it. Ignore it entirely when Claude Code is the driver.
- **`scripts/selftest.py`** — pipeline self-test: cascade examples, every
  workspace book against its gates, epub build + link integrity. Run it after
  changing scripts or lists. (Device fonts are prebuilt in `extras/fonts/`;
  charset-subsetting was retired — see readers.md for why sparse fonts fail.)
- **`prompts/planner.md`, `prompts/scribe.md`, `prompts/glossary_editor.md`** —
  the three LLM-role briefs.

## Three roles + deterministic scripts

The pipeline is one model wearing three hats, with scripts doing everything
mechanical between them:

- **Planner (LLM, once per book)** — turns source material + level into
  `plan.json` (outline with per-chapter beats). See `prompts/planner.md`.
- **Scribe (LLM, once per chapter)** — writes chapter N from the brief
  `gen_context.py` produces (and reworks it from flagged tokens on a fail).
  See `prompts/scribe.md`.
- **Glossary editor (LLM, once per chapter)** — `update_state.py` proposes every
  gloss-worthy first appearance (over-inclusive on purpose); the model prunes
  compositionally-transparent rows, keeps topic words, and fills blank glosses.
  See `prompts/glossary_editor.md`.
- **Deterministic scripts** — `gen_context.py` (brief), `validate.py` (grade),
  `update_state.py` (track used words + what happened + propose glossary),
  `build_epub.py` (assemble). No LLM judgement.

The planner invents structure; the scribe invents prose; the glossary editor
applies pedagogical judgement; the scripts never invent anything — they segment,
count, gloss, and record.

## Two drivers (the model seam is file-based)

The LLM steps read and write files (brief in → chapter out; raw glossary in →
curated glossary out), so *who fills them* is pluggable. Two ways to drive the
exact same scripts:

- **Claude Code drives** (interactive, rides your Claude subscription) — Claude
  Code follows the orchestration loop below itself: runs the scripts as Bash
  tools, writes each chapter and curates each glossary inline. No `config.json`
  needed. Best for chapter 1 and the human-QA gate.
- **`headless/run_book.py` drives** (headless, any model) — the optional
  driver in `headless/`, for running without Claude Code. Calls an
  OpenAI-compatible endpoint for the model steps. Default is NVIDIA NIM (free
  tier) with Kimi K2 (most natural Chinese prose; one-line swap to Qwen / a
  local Ollama or vLLM server). By default it runs the **whole book in one
  go** — readers are cheap to regenerate, so the convenience wins. Config
  lives in `headless/` (found by absolute path, so run from the repo root):
  ```
  H=ai-tools/graded-reader/headless
  cp $H/config.example.json $H/config.json      # then set model / base_url
  printf '%s' 'nvapi-...' > $H/secrets/nim.key   # gitignored
  .venv/bin/python $H/run_book.py workspace/BOOK                 # whole book, unattended
  .venv/bin/python $H/run_book.py workspace/BOOK --pause-after 1 # opt-in QA stop after ch1
  .venv/bin/python $H/run_book.py workspace/BOOK --from 3        # resume from chapter 3
  ```
  `headless/config.json` and `headless/secrets/` are gitignored. The runner
  stops (doesn't guess) if a chapter still fails after the rework cap —
  add-and-gloss stays a human/Claude-Code judgement call.

## The validation cascade

Each Han-containing token is classified:

| tier | rule | outcome |
|------|------|---------|
| a | token is a list word | **known** |
| b | token is a chengyu/expression | **known** (in list) |
| c | single character met in any known word | **known** |
| d | number grammar (第五名, 十二个) or a concatenation of list words (很快, 只能) | **composed** (in list) |
| e | multi-char word, not listed, every char known | **stretch** (keep + gloss once) |
| f | otherwise (contains an unknown character) | **flagged** (out of list) |

Tier (d) exists because jieba merges frequent collocations into single tokens.
Without it, ordinals and known-word compounds eat the stretch budget and the
rate stops measuring genuine reach — a learner who knows 很 and 快 *recognizes*
很快; only combinations like 山上 or 睡着 are real (gloss-worthy) stretches.

**Five gates.** The rate gates are per segmented token (not per character);
`out_of_list_rate = flagged / counted`, `stretch_rate = stretch / counted`:

| gate | default | why |
|---|---|---|
| `threshold` — max out-of-list | 5% | above it the text stops being readable at level |
| `min_out_of_list` — **min** out-of-list | 0 (books opt in, ~1.5%) | **a floor, not a typo.** Text that is 100% in-list is too easy to learn from; a little new vocabulary in context is where acquisition happens (i+1). A chapter at 0% fails as *too easy*. |
| `max_stretch` | 15% | compositional guesses shouldn't carry the text |
| `min_chars` | 0 (books opt in, ~800) | a chapter must be a real episode |
| `min_expressions` | 0 (books opt in, ~5) | distinct `expressions.tsv` constructions used |

The floors default to 0 so older books keep passing; new books set them in
`plan.json` → `validation`. They exist because **only what a script measures
actually happens**: length and expression targets lived in the prompts for a
long time and were quietly missed every single chapter, while the script-checked
vocabulary gates were met 100% of the time. Gates default to the book's `plan.json` validation params; CLI flags
override. `validate.py BOOKDIR` checks every chapter in `book.json` at once.

## The orchestration loop

**Once per book — Planner.** Produce `plan.json` per `prompts/planner.md`:
**research the source first** (don't plan from memory), write a **story bible**
(cast, relationships, setting, motifs, and the full event chain), and only then
divide that chain into chapters with a length budget. Seed obvious story names
into the book's own `workspace/<slug>/vocab.tsv`.
Aim for a **substantial book**: follow the source story's events across enough
chapters (roughly 8–12 for a short tale, more for a longer source) and make each
a meaty episode (~450+ chars), not a summary — see planner.md's "Make the book
substantial".

**Then, for each chapter `N`:**

1. **Build the scribe brief** (deterministic):
   ```
   python scripts/gen_context.py BOOK --chapter N --out BOOK/build/chNN-brief.md
   ```
   It pulls the beat, the story-so-far recaps, the `introduced` set, the topic
   words, and the permitted vocabulary grouped by band.
2. **Write the chunk — Scribe.** Following the brief and `prompts/scribe.md`,
   write `BOOK/chapters/chNN.md` (a `# 第N章` title, paragraphs, then a final
   `RECAP:` line). Stay inside the permitted vocabulary; prefer the lowest band;
   reuse words. Base it on well-known source material so effort goes into
   grading, not plot. Expect culturally loaded passages to rework more.
3. **Validate** (deterministic):
   ```
   python scripts/validate.py BOOK/chapters/chNN.md --json
   ```
4. **Rework OR accept.**
   - **Pass** → accept.
   - **Fail** → take `flagged_tokens` (worst first) and rewrite to avoid them,
     keeping the story. Re-validate. **Cap reworks at `rework_cap` (default 3).**
   - **After the cap**, if a word keeps recurring because the topic genuinely
     demands it, do **not** keep rewriting: take the **add-and-gloss** path — add
     it to `lists/personal.tsv` (pinyin + gloss) and to `plan.json` →
     `introduced.add_and_gloss`. It becomes known for all later chapters and is
     glossed once here. (A content word that recurs many times but squeaks under
     the threshold is also an add-and-gloss candidate, not a pass to ignore.)
5. **Update state** (deterministic — does the harvest, glossary, and tracking):
   ```
   python scripts/update_state.py BOOK --chapter N
   ```
   It writes `BOOK/build/chNN-glossary.tsv` (gloss-worthy first appearances:
   topic words + compositional stretch, minus anything already in `introduced`),
   appends them to `introduced.words`, files the `RECAP:` line into the outline
   (and strips it from the chapter), and wires `book.json`.
6. **Curate the glossary — Glossary editor (LLM).** The proposed TSV is
   over-inclusive on purpose. Per `prompts/glossary_editor.md`, prune
   compositionally-transparent rows (山上, 很多, 一天…), keep topic words, and
   fill any blank gloss. This is the model's judgement call, not a human's — the
   `run_book.py` driver does it automatically; Claude Code does it inline.
7. **Next chapter.** Repeat. Later chapters re-segment against the updated lists,
   so add-and-gloss words no longer flag and introduced words aren't re-glossed.
8. **Annotate, then assemble** (after chapters are accepted). The builder is
   generic — it renders `{word|reading}` and knows nothing about pinyin — so
   this service marks the readings first, then hands over a book the builder
   can render without thinking:
   ```
   python scripts/annotate.py BOOK --reading-style after
   python ../../epub-builder/scripts/build_epub.py BOOK --out BOOK/build/book.epub
   ```
   `annotate.py` segments each chapter, marks the first occurrence of every
   glossary word as `{词|pīnyīn}` into `build/annotated/`, and points
   `book.json` there. `chapters/*.md` stays the human-readable source that the
   scribe writes and `validate.py` grades.
9. **Verify the EPUB** (deterministic, shared with pdf2epub): confirm the
   output is a structurally sound EPUB — mimetype first/stored, manifest ⇄
   zip parity, well-formed XHTML/OPF, and every glossary link/fragment
   resolves.
   ```
   python ../../epub-builder/scripts/verify_epub.py BOOK/build/book.epub
   ```

## Gates that are NOT automated

- **The validator checks vocabulary only, never quality.** The QA read is
  *optional and off by default* — readers are cheap to regenerate, so the
  default is to run the whole book unattended and just reread/regenerate if a
  result disappoints. When you do want the safety check (a new source or level
  you haven't tried), opt in with `--pause-after 1`: the runner stops after
  chapter 1 so a human can confirm it reads naturally and the grading is
  *pleasant*, not merely legal, before the rest of the book generates.
- **Pinyin display depends on the target device.** On the X3, ruby and
  interlinear are device-confirmed broken; ship `reading_style: after` (the
  default) or `none`. Ruby is kept for capable readers (phones). The style is
  declared in `book.json`, so re-rendering a book differently is one field plus
  a rebuild.
  ```
  Device notes: `extras/readers.md` at the repo root.

## Book layout

```
BOOK/
  book.json            {title, author, language, reading_style, cover?, chapters:[...]}
  vocab.tsv            this book's names/places/props (temporary; dies with the book)
  images/cover.png     optional cover (prepare_cover.py; see "Cover")
  plan.json            outline + introduced set + validation params
  chapters/chNN.md     chapter source (# title, ## section, paragraphs)
  build/annotated/     generated: chapters with {词|pīnyīn} marks — the builder's input
  build/               harvest TSVs, glossaries, .epub output
```

Worked example under `workspace/`: `being-earnest` (诚实的重要, HSK 3, 10 ch) —
plan with story bible, per-chapter glossaries, and a built EPUB. Superseded
books are deleted rather than kept: once the generator improves, older output
is noise, and git history holds it if we ever want to look back.

## Cover

Give each reader a cover with the shared tool
`epub-builder/scripts/prepare_cover.py` (same one pdf2epub uses). The default
template is Chinese-themed — a parchment panel over a study scene — and the
book's title is drawn into the panel in **LXGW WenKai** (the kaiti hanzi that is
WenZilla's Chinese half, so the cover matches the reader's body face). The font
is rasterised into the PNG at build time; wrapping is CJK-aware (breaks between
hanzi).

```bash
.venv/bin/python epub-builder/scripts/prepare_cover.py \
    extras/default-covers/graded-default.png --title "愚公移山" \
    --title-config extras/default-covers/graded-default.json \
    --out BOOK/images/cover.png
```

Then set `"cover": "images/cover.png"` in `book.json`; the builder embeds it.
A user can override by dropping their own image and pointing `--title-config` at
it (or its own JSON), or skip the title for a cover that already has one.

## Build order (when starting a new reader)

1. Scaffold against a small list and ONE chapter (already done for HSK 1-3).
2. Get validate + build_epub green on that one chapter end to end.
3. Confirm the reading style renders on the target reader (on the X3 that's
   settled: `reading_style: after`; `ruby` is device-confirmed broken).
4. Only then run the full loop for the remaining chapters.

## Setup

```
python -m venv .venv && .venv/bin/pip install jieba pypinyin
```
On Debian/Ubuntu, install jieba inside a venv — the system setuptools breaks
jieba's legacy `setup.py` (`install_layout`). Run the scripts with `.venv/bin/python`.

## Adjusting level

Change which bands count as "known" by editing `lists/`. `hsk.tsv` currently
carries HSK 1-4; for a tighter target, trim bands out, and for a higher one,
append more (mirror any new band in `gen_context.py`'s `BAND_ORDER`). The
pipeline is level-agnostic — it grades against whatever the lists contain.
Files in this package (21)
  • SKILL.md 18 KB
  • requirements.txt 1 KB
  • headless/config.example.json 1 KB
  • headless/llm.py 5 KB
  • headless/run_book.py 10 KB
  • headless/secrets/README.md 1 KB
  • lists/chengyu.tsv 39 KB
  • lists/expressions.tsv 5 KB
  • lists/hsk.tsv 273 KB
  • lists/personal.tsv 1 KB
  • lists/supplement.tsv 3 KB
  • prompts/glossary_editor.md 2 KB
  • prompts/planner.md 6 KB
  • prompts/scribe.md 4 KB
  • scripts/annotate.py 6 KB
  • scripts/build_hsk_list.py 5 KB
  • scripts/gen_context.py 8 KB
  • scripts/selftest.py 4 KB
  • scripts/update_state.py 8 KB
  • scripts/validate.py 16 KB
  • scripts/vocab.py 12 KB

Versions

The database has no other skills named graded-reader.

Database snapshot: 13.11.2026 · package version 73a0ef896bcd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100chinese-dictation
    Generate Chinese (traditional/simplified) dictation practice — extract words+pinyin from a screenshot, produce an HTML page with audio that reads each word aloud with configurable pause between words. Use when user says "听写"、"聽寫"、"语文听写"、"听写练习"、"dictation"、"做个听写"、"听写卡"、"听写音频".
  • 100epub-builder
    Assemble an EPUB from the suite's common book format (book.json + chapters/*.md) for the Xteink X3 e-reader. Use when a book directory is ready to be built into an EPUB, when changing EPUB output (CSS, nav, packaging), or when a task needs to know the builder's input contract.…
  • 100wechatreading-vocab
    Turn the English words and phrases the user highlighted in a WeChatReading (微信读书) book into a vocabulary-in-context book. Each word gets a card with its American IPA (from the user's OALD9) and an example sentence tied to the chapter, and the result is a WeChatReading-friendly…
  • 100runcible-book
    Use when a subject should become a Runcible Book: a topic, a syllabus, a table of contents, or new chapters for a Book that already exists. Triggers on: 'add a book to Runcible', 'teach Runcible music theory', 'make a Runcible book', 'turn this syllabus into chapters', 'new…
  • 95vibe-reading
    Intelligent book reading and analysis skill. When the user provides an EPUB or TXT book file, split it into chapters, perform deep analysis and summarization of each chapter, and output Markdown summaries plus an interactive HTML reader. Works with any LLM model that OpenClaw uses.
  • 100book-summarizer
    Distills a book into a clear, faithful summary at the depth the reader wants — from a one-paragraph gist to chapter-by-chapter notes — surfacing the core thesis, key ideas, memorable examples, and actionable takeaways without distortion. Use this skill when a user asks to…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.