How to write a book with Claude Code or Codex: install to chapter one

How to install a novel-writing skill in Claude Code

You need Claude Code or the Codex CLI, Node.js and Python 3 (the installer uses npx; local checks run on Node and Python), and an empty folder for the book.

1. In a terminal, run npx skills add zenstory-ai/oh-story-claudecode -y -g. -g installs globally; rerun it to update.
2. Create a folder for the book and start Claude Code or Codex inside it.
3. Run /story-setup ($story-setup in Codex). It asks which agent you use and where to deploy, and merges any existing CLAUDE.md or config.
4. Read the deployment report. In Codex CLI, trust this project’s .codex/ configuration layer and review/trust new or changed hooks in /hooks; then open a new session in the same project folder.
5. Ask it to start a book (the Chinese trigger is 「帮我开书」); that goes straight to the long-form workflow. Unsure about length? Run /story, say you want to write a novel, and it asks long or short first.
6. Read the chapter one outline, then ask for chapter 1 (「写第1章」). The prose goes into 正文/ and a chapter check runs. On-target length commits tracking; a short or long chapter gets you the options first.

You can also tell the agent Install this skill https://github.com/zenstory-ai/oh-story-claudecode on any host that imports GitHub repos. For the Claude Code plugin marketplace, run claude plugin marketplace add https://github.com/zenstory-ai/oh-story-claudecode, then claude plugin install oh-story@oh-story-skills; commands then carry a prefix, as in /oh-story:story-setup. Overview: the Oh Story project page; source: GitHub.

Package installation, project deployment, and session loading are separate. The install command updates the skill package; story-setup deploys the current local package into this book’s project; the new session discovers the writing assistants. A deployment report alone does not show that hooks ran. The official OpenAI skills documentation, checked on September 30, 2026, supports explicit selection with $ or /skills. Its hooks documentation requires trust for the project layer and current hook definition; changed hooks need review again. An installer finishing does not establish that the outline guard is active.

Codex skills for novel writing and other hosts

A Codex deployment writes .codex/agents/, .codex/hooks.json, .codex/hooks/ and a root AGENTS.md. Full per-host details and known limits are in the repo's host deployment notes.

This table describes the adapter routes in the cited Oh Story version, rather than every host’s latest capabilities. Check deployed files, current-session loading, and hook trust separately. If a skill is missing, diagnose the environment before deciding to deploy again.

Installing Claude Code novel-writing skills on Windows and Mac

• Both systems use the same install command and need Node.js and Python 3. Setup tries python3, python, then py, and stops if none is found; install Python 3 and rerun /story-setup.
• On Windows the installer may print ENOENT ... mkdir yet end with Done!. Some skills did not install fully; rerun the same install command, then have story-setup check the reference bundle. Preserve any remaining error; the final Done! message is not evidence of a complete repair.
• If you clone the repo on Windows and point Codex straight at it, git needs core.symlinks=true. Installing as on this page and deploying into the writing project with $story-setup works as usual. Codex hooks on Windows run through a .cmd launcher that setup registers; the trust step is the same as on other systems.
• Claude Code hooks are .sh scripts, and setup marks them executable when it deploys.

Where Claude Code saves your novel: the project files

The manuscript is plain Markdown inside the book folder, so any editor can open it. Environment and manuscript files live apart:

Codex puts its environment files in .codex/ and a root AGENTS.md. A short story is simpler: one folder with 设定.md, 小节大纲.md and 正文.md. To browse them in a browser, run /story dashboard; the workbench listens only on 127.0.0.1, so the manuscript stays on your machine.

Oh Story novel-writing skills: all 13 commands

In Codex, swap the leading / for $, as in $story-long-write. Skills versus plugins and MCP: see agent skills for writers.

Why write a book with a skill pack: file memory and gates

In one long chat, early settings eventually get compressed away. Oh Story keeps settings, outlines, prose and tracking in separate folders: the chat writes, the folder remembers. Each chapter loads only the character states, open clues and settings it needs.

• No outline, no prose: guard-outline-before-prose.sh blocks the first creation of a prose file whose chapter has no outline. This is the guard behavior after the corresponding host deployment; untrusted Codex hooks or a skills-only host do not establish an active runtime block.
• Every chapter outline states a word target; if the field is empty, the workflow stops until you fill it in.
• The chapter workflow runs checks for length, AI phrasing patterns, repetition, truncation, and punctuation. Read the actual results for this run; passing them does not establish literary quality.
• Tracking is rebuilt whole from _tracking-state.json. The 上下文.md context card has 7 fixed sections and a 12KB cap, so a late chapter loads about as much state as an early one.
• Starting a book stops after settings, the volume outline and the first 10 chapter outlines. Prose needs a named chapter or a daily-update request, at most 3 chapters per round.

The fresh session matters because the 7 specialist agents (story-architect, narrative-writer, consistency-checker and others) register only at session start; an old session falls back to a single thread. See the chapter outline template and long-novel continuity for more.

Prose, outlines, tracking, and host diagnostics use their existing workflows. An environment check does not draft a chapter merely to prove installation; unverified session capabilities remain unverified.

Example: write chapter one with Claude Code from an empty folder

An original illustrative walkthrough of intended interaction and file destinations; this edit did not install an environment or produce this book.

Setup: make a folder called night-laundromat/, start Claude Code in it, run /story-setup and pick Claude Code. After the install report, quit and open a new session.

You: A long urban mystery. The lead works nights at a 24-hour laundromat; every night at 3 a.m. a silent customer washes the same raincoat caked in river mud. Start the book.

Saved: 设定/角色/ gets files for the clerk and the customer; 大纲/ gets the book outline, the volume one outline and the first chapter outlines. The workflow stops and waits.

You edit: in 大纲/细纲_第001章.md, move the customer's first words to the chapter's end and confirm the word target is filled in.

You: Write chapter 1.

Saved: the prose lands in 正文/第001章_章名.md; the check reports word count and phrasing hits; 追踪/上下文.md moves to chapter 1 and logs the river mud as an open clue.

Next day, open a fresh session in the same folder and ask for chapter 2 or a daily update. Have drafted chapters already? Start with import and continue.

Claude Code novel-writing skill not working? Common fixes

• **/story-setup does nothing.** Marketplace installs use /oh-story:story-setup; Codex uses $story-setup or /skills; OpenCode takes plain language; OpenClaw uses /skill story-setup or the skill's name, plus a new session if new skills do not appear.
• Setup says the reference bundle is incomplete. Reinstall the way you installed (rerun the npx command or reinstall from the marketplace panel), then run /story-setup again.
• **/story-review shows Fallback: ... -> solo.** You are in the old session or the agents did not register. Open a new session.
• Started a book, got no prose. A new book stops at the chapter outlines. Review them, then ask for chapter 1.
• Prose writing gets blocked. That chapter has no outline; add 大纲/细纲_第NNN章.md first.
• **A hand edit to 追踪/上下文.md fails the check.** The context card, clues, character states and timelines are generated from _tracking-state.json, so hand edits fail. Ask the skill to recommit that chapter's tracking as a revision and the tool rebuilds them. To change what happens in a written chapter, ask it to revise the chapter (「修改第N章」); the revision updates tracking too.
• Nothing changed after an upgrade. Rerun /story-setup in the book folder, then open a new session.
• Confirming the install. Ask the agent to check the writing environment with story-setup; check mode only reports and leaves the project as it is.

FAQ

Where does Claude Code save my novel?

In the book folder where you started Claude Code: one Markdown file per chapter under 正文/, outlines under 大纲/, settings under 设定/. Back up the folder and you have backed up the book.

Do Claude Code novel-writing skills need a GPU or a separate model?

Prose uses your agent’s model and does not require a local GPU; deterministic checks use Node and Python. Covers have a separate generation route. Use built-in image generation when the current Codex session actually exposes it, without a separate API key. If that tool is absent or the author explicitly chooses the API, story-cover’s fallback needs GPT_IMAGE_API_KEY. Check available tools before selecting the route.

Can I use these novel-writing skills in Codex?

Yes. The install command is the same as for Claude Code. In Codex, deploy with $story-setup, trust the project .codex/ config and hooks, open a new session, then write with commands like $story-long-write.

Related reading

• Oh Story→
• Agent skills for writers: prompts, skill packs, plugins, MCP→
• Chapter Outline Template for a Web Novel→
• How to Draft a Novel Chapter from an Outline→
• Continue your unfinished novel with AI: import into Oh Story→