Story Skills documentation
This is the documentation for Story Skills: Agent Skills for writing fiction, plus the story CLI that checks and maintains the project files. Use this page to find the right guide, whether you are writing a book, looking up a command or field, or changing Story Skills itself.
If you have not used Story Skills before, start with Getting started. If you write in claude.ai and don't use a terminal, start with Writers: start here instead.
How the pieces fit
A story project is a folder of markdown files with YAML frontmatter. The skills do the creative work, such as outlining, drafting, and revising, and write those files. The story CLI does the mechanical work: it validates the files, rebuilds registries, counts words, checks links and continuity, and builds the finished book. It never composes or revises prose. Core concepts explains the model in full.
Start here
Pick the route that matches what you came to do. Each one takes four pages; read the rest as you need them.
I'm writing a book
- Getting started: install the skills and the CLI, then create a project and draft chapter 1.
- Writing workflows: which skills to use, in what order, from a first idea to a submission package or a published book.
- Skills catalogue: what each skill does and when your agent picks it up.
- Continuity and analysis: what the checks catch and how to act on their findings.
I'm installing skills for an agent or team
- Install the skills: Claude Code, Codex, the Agent Skills CLI, or a manual copy.
- How skills work: how an agent picks up a skill and finds the
storyCLI. - The bundled fallback CLI: the copy of the CLI that ships inside the skills for installs without the npm package.
- Automation and CI: run the checks on every pull request, draft chapters on a schedule, and publish a review copy for readers.
I'm changing Story Skills
- Core concepts: how a project is laid out, and how ids, registries, backlinks, and word counts work.
- Project format reference: every file, frontmatter field, and allowed value the CLI enforces.
- CLI reference: every
storycommand and option, with its output and exit codes. - Development guide: repository layout, tests, the bundled fallback, CI, and releases.
All pages
Guides
| Page | What it covers |
|---|---|
| Writers: start here | For writers without a terminal: downloading skill zips, uploading them to claude.ai, and what works without the CLI |
| Getting started | Installing the skills and CLI, and a first session from story init to a clean maintenance pass |
| Core concepts | The project model: files, frontmatter, entity kinds, ids, registries, backlinks, word counts, and how the work is split between skills and CLI |
| Writing workflows | End-to-end sessions: testing a premise, plotting first, discovery drafting, scene craft, theme and voice, research, revision passes, line editing, feedback and editorial review, submission, self-publishing, and adaptation |
| Continuity and analysis | The continuity engine (including travel times over location routes), exemptions, and the knowledge, context, timeline, prose, voices, pacing, clues, grid, names, diagram, progress, compare, report, next, and doctor commands |
| Writing in other languages | What works in each language and script: counting in words or characters, dialogue and sentences, word lists, build labels, fonts, right-to-left and vertical text, ids, and adding a language pack |
| Series | Linking sequels and prequels, story series, carrying characters and facts between books, and laying out a short-story collection or anthology |
| Import, export, and builds | Importing an existing draft, front and back matter, publishing metadata, and building markdown, EPUB, DOCX, Shunn, HTML review copy, print interior, narration script, retailer metadata sheet, Fountain screenplay skeleton, Twine and ink stories, story bible site (codex), and synopsis output |
| Editor integration | story lsp in VS Code, Neovim, Helix, Emacs, and other editors: findings as you type, go to definition, references, hover, id completion, rename, and quick fixes |
| Automation and CI | The GitHub Actions templates (checks, scheduled drafting, and the review copy with its reader-note issue form), exit codes and output streams, and pre-commit hooks |
Reference
| Page | What it covers |
|---|---|
| Skills catalogue | All 24 skills: triggers, the files each one reads and writes, the commands it runs, and its reference files |
| CLI reference | Every story command and option, with usage, output, and exit codes |
| Project format reference | The schema v2 file contract: every file, frontmatter field, allowed value, and registry, plus migration from older projects |
For contributors
| Page | What it covers |
|---|---|
| Contributing | The short version: adding a skill or a CLI command, the checks to run, commit style, and changelog entries |
| Development guide | Repository layout, CLI architecture, tests, the bundled fallback, schema and metadata checks, evals, skill authoring, CI, and releases |
| Changelog | User-visible changes in each release, including project format and CLI behaviour changes |
| Code of Conduct | The Contributor Covenant 2.1, which applies to everyone taking part |
Find it by task
| You want to... | Read |
|---|---|
| Install Story Skills | Getting started |
| Use the skills in claude.ai without a terminal | Writers: start here |
| Test whether an idea will carry a book, and pick its form | Writing workflows and the premise-workshop entry in the Skills catalogue |
| Start a new book | Getting started, then Writing workflows |
| Draft without an outline | Writing workflows |
| Bring in a draft you already have | Import, export, and builds |
| Pick the right skill for a request | Skills catalogue |
| Look up a command or flag | CLI reference |
| Look up a frontmatter field or allowed value | Project format reference |
| Understand a continuity error or warning | Continuity and analysis |
| Dismiss a finding on purpose | Continuity and analysis |
| Check pacing, scene outcomes, and chapter hooks | Continuity and analysis (story pacing) |
| Check a mystery's clues play fair | Continuity and analysis (story clues) |
| See which chapters advance each arc, as a table or CSV | Continuity and analysis (story grid) |
| Check that characters sound different | Continuity and analysis (story voices) |
| Check a new name before using it | Continuity and analysis (story names) |
| Draw a family tree, route map, timeline, or clue diagram | Continuity and analysis (story diagram) |
| Check travel times between places | Continuity and analysis and location routes in the Project format reference |
| Revise in named passes, from structure down to proof | Writing workflows (story passes) |
| Line edit or copyedit without losing the author's voice | Writing workflows and the line-editing entry in the Skills catalogue |
| Work with sensitivity readers, editors, permissions, or a co-author | Writing workflows and the editorial-review entry in the Skills catalogue |
| Write a book in a language other than English | Writing in other languages |
| Write a sequel or prequel | Series |
| Put together a short-story collection or anthology | Series |
| Build an EPUB, DOCX, or submission manuscript | Import, export, and builds |
| Build an HTML review copy, a print interior, a narration script, a retailer metadata sheet, or a screenplay skeleton | Import, export, and builds |
| Browse or share the story bible as a website | Story bible site |
| Self-publish: metadata, ISBNs, copyright page, print, launch | Writing workflows, Import, export, and builds, and the publishing entry in the Skills catalogue |
| Adapt the book for audio, screen, comics, or translation | Writing workflows and the adaptation entry in the Skills catalogue |
| Run the checks on every pull request | Automation and CI |
| Pick out files by frontmatter, such as draft chapters or the scenes a character is in | CLI reference (story list), and Saved queries for the filters you run often |
| Share a review copy that readers can annotate by paragraph | Automation and CI (review-copy.yml and the manuscript-note issue form) |
| Upgrade an older project | Project format reference |
| Change the CLI or a skill | Contributing, then the Development guide |
| See what changed in a release | Changelog |
Example projects
The repository includes eleven sample projects in examples/. The pages above use them for their sample output.
| Example | Shows |
|---|---|
the-last-ember | A fantasy project with a style sheet, front matter, and an arc. Book 1 of a two-book series. |
the-fall-of-the-citadel | The prequel to The Last Ember, linked with precedes and shared fact ids |
harbor-of-second-light | A science-fiction coastal mystery with populated continuity state, knowledge entries, publishing metadata, a location route, a pronunciation, and a chapter beat |
the-gull-rock-light | A short second-person branching story: chapter choices for story build --format twee and --format ink |
bo-and-the-missing-moon | A 32-page picture book (form: picture-book): one chapter per spread, a scene record and page-turn hook per spread, and a pagination plan with spread briefs |
the-left-luggage-office | The first three episodes of a weekly serial (form: serial): season-goal, episode-question, per-episode target-words and hook, and a promise paid off in an episode not yet written |
salt-and-lantern | An anthology of three short stories: the editor in story.md editor, each story's writer in its chapter author, title-only headings through the chapter-heading label, and an acknowledgements page |
the-unraveled-thread | A village mystery that is broken on purpose to show the main kinds of continuity finding, plus clues (one a red herring) for story clues and scene outcomes and chapter hooks for story pacing |
quatre-heures-dix-sept | A short story in French (language: fr): dialogue in guillemets with French no-break spaces, the French word lists, and French build labels |
kirimi-eki-no-wasuremono | A short story in Japanese (language: ja): counted in characters, target-characters, corner-bracket dialogue, and writing-mode: vertical |
laysat-lil-bay | A short story in Arabic (language: ar): right-to-left builds and Arabic punctuation |
Other resources
- README: the project overview.
schemas/story.schema.json: the project format as a JSON schema.schemas/result.schema.json: the--jsonoutput of the CLI as a JSON schema.templates/github/: the GitHub Actions workflows and the reader-note issue form to copy into a story repository.AGENTS.md: the short rules for coding agents working on this repository.