| name | book-writing-workspace |
| description | Operate a reusable technical book manuscript workspace with writing structure, reader persona SSOT, review rules, and optional Markdown to Re:VIEW/PDF support. Use when organizing a book manuscript repo, defining or reviewing target readers, standardizing chapter/section files, setting writing/review agents, or assessing an existing writing workspace. Triggers on book writing workspace, reader persona, reader audience, 読者ペルソナ, persona SSOT, technical book project, 執筆ワークスペース, manuscript workflow, and Re:VIEW workspace. |
| argument-hint | 本のテーマ、原稿リポジトリ名、使いたい執筆フロー |
| user-invocable | true |
| license | CC BY-NC-SA 4.0 |
| metadata | {"author":"yamapan (https://github.com/aktsmm)"} |
Book Writing Workspace
Create and maintain a reusable manuscript workspace with folders, writing agents, instructions, review rules, and optional Markdown -> Re:VIEW -> PDF support.
When to use
- Book writing, technical writing, 執筆プロジェクト, Re:VIEW
- Assessing or standardizing an existing book manuscript repository
- Creating a new technical writing project from templates when needed
- Setting up Markdown → Re:VIEW → PDF workflow
- Upgrading an existing manuscript workspace so it can generate Re:VIEW output and printable PDFs
- Standardizing chapter/section file layout, writing rules, review workflow, and page allocation
- Adding optional Re:VIEW/PDF support without turning the writing workspace into a general Git or publishing operations toolkit
Quick Start
Start by assessing the manuscript workspace, even when creating a new project:
- Confirm the main manuscript lives in
sections/ and uses one file per section.
- Confirm outlines or key points live separately from final manuscript files.
- Confirm chapter intro files use kebab-case naming (e.g.
00-introduction/00-introduction.md).
- Locate the workspace's declared reader-persona SSOT; do not force a new file when an existing overview or planning document already owns it.
- For a new workspace, use
docs/reader-personas.md to define the primary persona, secondary personas, prior knowledge, and completion outcomes.
- Confirm writing, heading, notation, page allocation, and review rules are available.
- Decide whether Re:VIEW/PDF output is needed for this project; keep it optional unless the workflow requires it.
Operating Workflow
When the workspace already exists, do not stop at setup-oriented advice. This skill should also support:
- Normalizing manuscript folders and section naming.
- Keeping outlines, drafts, final manuscript, and images aligned by chapter.
- Running focused writing and review loops until P1/P2 issues are resolved.
- Applying reviewer fixes without leaving outlines, chapter maps, question digests, and progress trackers out of sync.
- Reviewing each chapter against the book-specific reader persona and expected outcome.
- Checking word count targets and source confidence before finalizing text.
- Enabling Re:VIEW/PDF support only when the project needs reproducible output.
Bootstrap Workflow
Use the setup script only when creating a new workspace or adding missing structure deliberately.
python scripts/setup_workspace.py `
--name "project-name" `
--title "Book Title" `
--path "D:\target\path" `
--chapters 8
# Include Re:VIEW/PDF scaffolding only when needed.
python scripts/setup_workspace.py `
--name "project-name" `
--title "Book Title" `
--path "D:\target\path" `
--chapters 8 `
--with-review
- Gather info: Project name, title, location, chapter count
- Run script:
scripts/setup_workspace.py
- Review output: Confirm README, agents, instructions, and docs were created
- Customize: Edit
docs/reader-personas.md, docs/page-allocation.md, docs/schedule.md, and .github/copilot-instructions.md. If --with-review is used, also customize config/review-metadata/project.yml.
Git workflows are project-specific. Do not add generic commit/push prompts here; follow the repository's existing version-control conventions.
Metadata, migration, converter verification, and sync-back rules live in references. Keep the main SKILL focused on manuscript structure and writing workflow.
Generated Workspace
- Manuscript folders under
keypoints/, sections/, and images/
- AI workflow files under
.github/agents/ and .github/instructions/
- Project docs such as
README.md, docs/reader-personas.md, docs/page-allocation.md, and docs/schedule.md
- Helper scripts such as
scripts/count_chars.py
- Optional Re:VIEW scripts and metadata when
--with-review is used
Recommended Writing Unit
- Use 1 file = 1 section as the default manuscript unit.
- Keep chapter intro in
{NN}-{slug}/{NN}-{slug}.md and section files alongside it.
- For PDF/Re:VIEW output, heading levels define hierarchy, while file split mainly improves authoring and review workflow.
Agents Overview
| Agent | Role | Default |
|---|
@writing | Write and edit manuscripts | Yes |
@writing-reviewer | Review manuscripts (P1/P2/P3) | Yes |
@converter | Convert Markdown to Re:VIEW | Only with --with-review |
Dependencies
| Tool | Purpose | Required |
|---|
| Python 3.8+ | Scripts | Yes |
| Git | Version control | Yes |
| Docker | Re:VIEW PDF build | Optional, only with --with-review |
Reference Map
Optional Build Pipeline
For workspaces that add conversion or PDF rendering, apply build pipeline gates. Keep project-specific commands, dependency versions, and formatter rules in the generated workspace.
Done Criteria
