/chapter-writing

name: chapter-writing
description: This skill should be used when the user asks to "write a chapter", "next chapter", "chapter outline", "draft chapter", "continue the story", "write a scene", "outline a chapter", or wants to write prose for a story project. NOT for planning a scene's structure, subtext, or outcome (use scene-craft), drafting without an outline (use discovery-drafting), or revising existing chapters (use revision-continuity).

Chapter Writing

Overview

Write story chapters using an outline-first workflow. Gathers context with `story context`, which keeps later chapters out, builds a beat-by-beat outline for approval, then writes full prose. After writing, records the scene dates, the continuity state, and each setup planted or paid off in the one record that owns it, and rebuilds registries with `story reindex`.

Prerequisites

A story project must already exist with at least:

• `story.md` (story bible)
• At least one character in `characters/`
• A plot structure in `plot/_index.md` (recommended but not required for first chapters)

Prose Pass and Companion Skill

The in-repo `line-editing` skill owns the prose-quality pass (line edit, voice differentiation, copyedit, read-aloud, proof). It ships with Story Skills, so it is always available: run it on a drafted chapter before marking it `revised`.

The external `better-writing` skill is an optional complement for general prose quality and anti-generic writing checks. Before drafting or revising chapter prose, check whether it is available in the active agent environment. Detect it by looking for its skill directory in the configured skills paths:

ls -d ~/.claude/skills/better-writing .claude/skills/better-writing ~/.agents/skills/better-writing .agents/skills/better-writing skills/better-writing 2>/dev/null

• If a `better-writing` directory exists (containing `SKILL.md`), use it for prose quality, voice calibration, anti-generic writing checks, and the final pre-flight pass before saving the chapter.
• If `better-writing` is not installed, continue with this skill's built-in writing guidelines (`references/writing-guidelines.md`). Do not ask about it every session: offer it once, when you draft the project's first chapter, by pointing the user at [forjd/better-writing](https://github.com/forjd/better-writing) and asking whether they want to install it. After that, mention it only if the user asks about prose-quality tools, and never again once they decline. Do not run any installer without explicit approval.

Outline-First Workflow

1. Gather Context

If the chapter you are drafting already has a file with its `pov` and `characters` set (for example a planned chapter that `story next` names), start with its packed context:

story context chapter-{NN} --path .

It prints, within a token budget (`--budget`, default 6000), the chapter's outline and cast, the `story.md` essentials (including the book's language, writing mode, chapter numerals, and count unit) and `style-sheet.md` rules, the POV character's knowledge and state at that point, cards for the characters on the page and the chapter's locations (with their `progressions` applied at this chapter), open promises, clues, and questions, and summaries of the previous scenes. Knowledge uses the same rule as `story knowledge`: the character knows a fact when its `learned-in` chapter is not after the target in story time (by date when both chapters are dated, otherwise by chapter number). A line marked `reader-knowledge` may be used in the prose. A line marked `character-knowledge` and `do not reveal` is known to the POV from a flashback the reader has not reached; write them as knowing it, and do not put the fact on the page. Everything else from a later chapter is left out. Add `--json` if you would rather read the items as data. For a new chapter, run it after step 2 instead.

Draft from that output, and do not open project files for background. If it ends with "Left out to fit the budget", do not open the files that list names, even though the line under it says to read them: they are whole files, and context filtered their items to the target. `continuity/state.md` holds knowledge learned later, character and location files hold later `progressions`, and promise and clue files hold their payoffs. Instead rerun with a larger `--budget`, or run with `--json` and use the `text` of each item in `sections` whose `included` is `false`, which is already filtered. Context already left out anything past the target: `continuity/state.md` is the full current snapshot, and a character's state from it is included only when `current-chapter` is before the target. `plot/timeline.md`, `continuity/questions/_index.md`, `continuity/promises/_index.md`, `plot/_index.md`, active arc files in `plot/arcs/`, and the other `_index.md` registries hold later beats or whole-book state, and the previous chapter is already covered by the recent scene summaries. Do not open them while drafting; the one exception is the arc `## Foreshadowing` rows for this chapter, which the outline step reads.

The packed context's Story essentials give the book's `language` (a BCP 47 tag; `en` when unset), writing mode, chapter numerals, and count unit, so you do not need to open `story.md`. Draft in that language, with its dialogue punctuation as the style sheet records it. If the style sheet records none and the book is not in English, settle it with the user first (see `../line-editing/references/language-conventions.md`). If the packed context has no style-sheet section and no left-out item names `style-sheet.md`, the file is missing: draft normally and suggest the `voice-style` skill once a chapter exists.

2. Determine Chapter Scope

Ask the user:

• What should this chapter cover?
• Whose POV?
• Which location(s)?

For a planned chapter, suggest the next beats from its packed context: its outline, the arcs it advances, and the open promises, clues,