handbook
Document Production Workflow — generates searchable, themed handbooks as static sites (GitHub Pages). Three modes: standalone handbook, lecture companion (reads a slide pipeline's slide_deck.md — co-deck integration), full course site. Responds to "make handbook", "create handbook", "build course site", "companion handbook" (triggered by Korean phrases too). H-Stage pipeline (H-0 through H-7) for creation. M-Stage maintenance mode (M-1 through M-5) upgrades existing handbooks: upstream sync, chapter add/rename/renumber, schedule consistency. Fielded references (intro-to-ai-harness, multi-agent-harness-handbook) ship four languages (ko canonical + en/ja/es). Korean-language authoring characteristics (register, spacing, proofreading pass, check interplay) are first-class — see references/KOREAN_LANGUAGE.md. Independent from slide pipelines. Promoted from co-deck to common (2026-08-30) — usable by any variant.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- handbook
- owner
- pm
- scope
- common
- status
- active
- version
- 0.6.0
- metadata
- { "triggers": [ "make handbook", "create handbook", "build course site", "companion handbook", "update handbook", "handbook sync", "handbook maintenance" ] }
- attribution
- { "note": "Inspired by beret21/teachme. Built from scratch — no original code copied. 2026-09-20: `add` command, strictest-Korean-proofreading, and add-only-edit safety adopted from the teachme v0.3.1 feature comparison.", "source": "https://github.com/beret21/teachme", "license": "MIT" }
- description
- Document Production Workflow — generates searchable, themed handbooks as static sites (GitHub Pages). Three modes: standalone handbook, lecture companion (reads a slide pipeline's slide_deck.md — co-deck integration), full course site. Responds to "make handbook", "create handbook", "build course site", "companion handbook" (triggered by Korean phrases too). H-Stage pipeline (H-0 through H-7) for creation. M-Stage maintenance mode (M-1 through M-5) upgrades existing handbooks: upstream sync, chapter add/rename/renumber, schedule consistency. Fielded references (intro-to-ai-harness, multi-agent-harness-handbook) ship four languages (ko canonical + en/ja/es). Korean-language authoring characteristics (register, spacing, proofreading pass, check interplay) are first-class — see references/KOREAN_LANGUAGE.md. Independent from slide pipelines. Promoted from co-deck to common (2026-08-30) — usable by any variant.
- last_reviewed
- 1789862400000
- prerequisites
- research (optional — standalone mode has no prerequisites)
02 资源文件 36
- 资产文件assets/css/handbook-components.css47.3 KB
- 资产文件assets/css/handbook-variables.css6.3 KB
- 脚本assets/js/copy-code.js2.3 KB
- 脚本assets/js/dark-mode-toggle.js5.4 KB
- 脚本assets/js/inpage-search.js10.7 KB
- 脚本assets/js/lang-switcher.js10.2 KB
- 脚本assets/js/site-search.js14.4 KB
- 参考文档examples/course/chapter_01.html3.7 KB
- 参考文档examples/course/chapter_02.html3.1 KB
- 参考文档examples/course/course-overview.html7.0 KB
- 参考文档examples/course/index.html3.8 KB
- 参考文档examples/course/instructor-guide.html8.9 KB
- 参考文档examples/handbook/chapter_01.html3.9 KB
- 参考文档examples/handbook/chapter_02.html5.0 KB
- 参考文档examples/handbook/chapter_03.html4.9 KB
- 参考文档examples/handbook/index.html3.0 KB
- 参考文档examples/minimal/chapter_01.html3.8 KB
- 参考文档examples/minimal/index.html2.1 KB
- 参考文档references/AUTHORING_GUIDELINES.md70.3 KB
- 参考文档references/BUILD_GUIDE.md9.6 KB
- 参考文档references/I18N_PARITY_PLAYBOOK.md4.4 KB
- 参考文档references/KOREAN_LANGUAGE.md5.5 KB
- 参考文档references/MAINTENANCE_PLAYBOOK.md8.2 KB
- 参考文档references/QUALITY_CHECKLIST.md13.1 KB
- 参考文档references/SECTION_TYPES.md3.3 KB
- 参考文档references/validation/NAV_VALIDATION.md3.8 KB
- 其他templates/.gitignore30 B
- 其他templates/.nojekyll—
- 参考文档templates/base.html6.6 KB
- 参考文档templates/chapter.html11.5 KB
- 参考文档templates/course-overview.html11.5 KB
- 参考文档templates/examples.html12.9 KB
- 参考文档templates/index.html9.3 KB
- 参考文档templates/instructor-guide.html18.4 KB
- 参考文档templates/manual.html9.6 KB
- 参考文档templates/quiz.html11.7 KB
03 SKILL.md 正文
Context
Generates searchable, themed handbooks as static sites deployed to GitHub Pages. Supports three modes:
- Standalone: Topic-based handbook built from scratch
- Companion: Reads cached slide-pipeline outputs (co-deck integration) (Research Package, Images, References, Diagrams, Versions) without re-executing the 11-Stage pipeline
- Course site: Full course with Course Overview + Instructor Guide + chapters
Dark mode is automatic (3-layer: :root light → @media prefers-color-scheme: dark auto-detect → .dark class manual toggle). Multi-language support via separate HTML files per language (chapter.html / chapter_ko.html / chapter_en.html).
When to Use
- PM Agent dispatches for handbook creation (H-Stage)
- User says "make handbook", "create handbook", "build course site"
- User says "companion handbook" (companion mode with co-deck integration)
- User says
교재 만들기,핸드북 생성,강의 자료 사이트
Execution Steps
Subcommands
| Command | Description |
|---|---|
new |
Create standalone handbook from topic |
add |
Extend an existing handbook in place — new chapter / quiz / appendix (routes through M-2a checklist) |
companion |
Create companion handbook from an existing co-deck (slide pipeline) project |
course |
Create full course site with Course Overview + Instructor Guide |
theme |
Apply a built-in theme to existing handbook |
verify |
Run the full validation chain — bun run ci (validate-handbook, symmetry, links, labels, authoring, doctor, a11y, spell, lint, external-links, search) |
sync-upstream |
Maintenance mode (M-Stage) — reflect upstream source changes into an existing handbook (see M-1) |
deploy |
Deploy to GitHub Pages |
doctor |
Run handbook-doctor.ts enhanced static analyzer (12 checks) |
H-0: Confirm Parameters
PM confirms with the user:
- Topic — handbook subject
- Language — primary content language (default:
ko) - Output directory — where to create the handbook (default:
handbook/) - Companion mode — whether to reuse slide-pipeline caches (yes/no; co-deck only)
Dark mode: No preference needed — auto-detect + manual toggle. All themes include 3-layer dark mode by default.
Korean canonical (default
ko): apply references/KOREAN_LANGUAGE.md — plain declarative register (평서체),순우리말-first preference, Korean proofreading pass before ship (script checks are English-only), and the Korean structural labels that nav/search rely on.
Companion mode cache reuse: If companion, H-1 is skipped. The following cached outputs are reused:
research_notes.md(Research Package)assets/images/fromimage-manifest.json(Image cache)assets/diagrams/*.svg(Diagram cache)- References from
source-verification.md(Reference cache)_versions/snapshots (Version cache)
H-1: Research (standalone only)
Dispatch research agent for web research. In companion mode, reuse cached research_notes.md.
H-2: Propose Structure
Dispatch the handbook-writer agent (co-deck; in other variants, dispatch docs-writer or the PM's authoring specialist) to propose section types and chapter structure based on SECTION_TYPES.md.
H-3: Write Content
Dispatch the handbook-writer agent (co-deck; in other variants, dispatch docs-writer or the PM's authoring specialist) to write chapter content following AUTHORING_GUIDELINES.md.
H-4: Generate Course Materials
Dispatch the handbook-writer agent (co-deck; in other variants, dispatch docs-writer or the PM's authoring specialist) to generate Course Overview (§14 — 9 required items) and Instructor Guide (§20 — lecture flow, expected questions, timing, frequent mistakes, demo order, evaluation criteria).
H-5: Quality Verification
Dispatch the handbook-reviewer agent (co-deck; in other variants, dispatch docs-writer or the PM's review specialist) to run:
bun run ci— the exact CI check chain in one command: validate-handbook (① structure, ② nav 4 checks, ③ tables), check-symmetry, check-links, check-labels, check-authoring, handbook-doctor, check-a11y, check-spell, check-lint, check-external-links, check-search. Prevents the doctor-green-but-CI-red failure mode.bun run check-i18n— cross-language content parity (heading/code-block counts, wrong-language links); for multilingual handbooks follow I18N_PARITY_PLAYBOOK.md (canonical-first regeneration workflow)- Apply fixes for any issues found
H-6: Apply Theme
Theme is a domain decision step (not just an asset):
- Select theme from built-in options (azure, graphite, teal, amber, indigo, native)
- Run
bun run apply-theme --theme <name> - Generate CSS with 3-layer dark mode
- Update
search-manifest.json(register new pages), then runbun run build-search-index --docs-dir docsto regeneratesearch-data.js—site-search.jsconsumes the generatedSEARCH_DATAglobal and is never edited by hand - Generate/update
<meta>tags
H-7: Security Scan + Deploy
PM runs secret scan, then deploys to GitHub Pages.
Maintenance Mode (M-Stage) — Existing Handbooks
For fielded handbooks (e.g. Handbooks/intro-to-ai-harness, Handbooks/multi-agent-harness-handbook).
Triggered by "update handbook", "handbook sync", 교재 업데이트, or an upstream standards change.
Full checklists: references/MAINTENANCE_PLAYBOOK.md. Ground rule (adopted from teachme): maintenance is add-and-amend only — never delete participant-facing content or user files; supersede instead. Each M-stage ends in bun run ci +
bun run check-i18n (all 4 languages green), a CHANGELOG entry, and a PR — handbooks are
independent git repositories and land PR-only, in English.
M-1: Upstream Sync
Reflect source-of-truth changes (e.g. ai-workspace-standards) into the handbook:
- Impact scan first — grep the docs for every touched identifier (flag names, category counts, script names, chapter/section references) and diff against the upstream source before writing anything.
- Korean canonical first, then
_en/_ja/_esin the same commit (I18N_PARITY_PLAYBOOK rule 2). - Verify claimed staleness against the chapter source — update handbook facts, never copy upstream prose blindly.
M-2: Structural Changes — Add / Rename / Renumber a Chapter
Mechanical sweep that must land together with the content (see playbook for the full list):
chapter-nav chains (prev/next symmetry), nav sidebars, index.html cards ×4 languages,
search-manifest.json + build-search-index, lecture guide (schedule row, instructor note,
quiz), course overview (schedule block, topics row), README curriculum, and — on renumber — a
localized number-variant sweep (13장/Chapter 13/第13章/Capítulo 13/Ch.13/Ch. 13/13章/Cap.13/Cap. 13, lowercase included) across hrefs, titles, SVG <text> labels, READMEs, and the manifest.
M-3: Schedule Consistency
Lecture guide and course overview are two views of one schedule — keep them in lockstep (blocks, times, totals, instructor-note order = teaching order). Recompute day/both-days totals programmatically from the table cells; never hand-sum. Update note strings that cite times (they drift when rows change).
M-4: Footer Baseline
The baseline date ("ai-workspace-standards main (YYYY-MM-DD)") lives in the FOOTERS constant
of scripts/update-footers.ts — bump the constant, run the script site-wide. Never hand-edit
per-page footers; version-row values (e.g. 문서 수집일) are page content and stay untouched.
M-5: Verification Triage
Run bun run ci + bun run check-i18n. Before attributing a warning/failure to your change,
reproduce it on a clean tree (git stash → rerun → git stash pop) — numeric-token warns and
transient external-link timeouts (e.g. YouTube) are usually pre-existing or flaky; retry once
before diagnosing.
Output Format
handbook/
├── docs/
│ ├── index.html
│ ├── search-manifest.json # Search index SSOT ({ path, title, lang } per page)
│ ├── chapters/
│ │ ├── chapter_01.html
│ │ ├── chapter_01_ko.html
│ │ └── ...
│ ├── course-overview.html
│ ├── instructor-guide.html
│ └── assets/
│ ├── css/handbook-variables.css
│ ├── css/handbook-components.css
│ ├── js/site-search.js # Consumes SEARCH_DATA — never edited by hand
│ ├── js/search-data.js # AUTO-GENERATED by build-search-index.ts
│ ├── js/copy-code.js # Shared copy-button impl (extract-copycode.ts)
│ ├── js/inpage-search.js
│ ├── js/dark-mode-toggle.js
│ ├── js/lang-switcher.js
│ └── images/
├── scripts/
│ ├── nav-utils.ts # Shared HTML-parsing helpers (vendored toolkit)
│ ├── validate-handbook.ts # Unified validator (--checks all = 8 groups)
│ ├── build-search-index.ts # Manifest → search-data.js generator
│ ├── validate-nav.ts # Runs broken-links + symmetry + labels + search checks
│ ├── check-structure.ts / check-symmetry.ts / check-links.ts / check-labels.ts / check-search.ts
│ ├── check-i18n-parity.ts # Cross-language parity gate (Check 13 of doctor)
│ ├── check-authoring.ts
│ ├── check-a11y.ts / check-spell.ts / check-lint.ts / check-external-links.ts
│ ├── apply-handbook-theme.ts
│ ├── update-footers.ts # FOOTERS constant = per-language site footer SSOT
│ └── handbook-doctor.ts
├── package.json # `bun run ci` = exact CI check chain
├── CHANGELOG.md
└── .github/workflows/validate-handbook.yml
Toolkit vendoring:
scripts/nav-utils.tsand the check scripts are a vendored toolkit shared by the fielded handbooks — fix bugs in the canonical copy (Handbooks/multi-agent-harness-handbook/scripts/) and re-vendor, never patch one copy only.
Related Skills
research— producesresearch_notes.md(standalone mode, H-1)storyline—slide_deck.mdconsumed in companion mode (H-2)theme-authoring— theme structure follows same CSS variable conventionhandbook-sync-audit— audits a handbook against its upstream source for drift
References
references/MAINTENANCE_PLAYBOOK.md— M-Stage checklists: upstream sync, add/renumber chapter sweep, schedule consistency, verification triage (2026-09-20 field incidents)references/KOREAN_LANGUAGE.md— Korean-canonical authoring: register,순우리말-first, spacing/typography, SVG labels, check interplay, proofreading pass, ko→out translation mappingsreferences/I18N_PARITY_PLAYBOOK.md— canonical-first multilingual maintenance rulesreferences/AUTHORING_GUIDELINES.md,references/SECTION_TYPES.md,references/QUALITY_CHECKLIST.md,references/BUILD_GUIDE.md
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.