story-skills

Plan, track, and draft fiction in markdown,
with a continuity checker that catches mistakes before readers do.

Quick start  ·  Continuity engine  ·  Skills  ·  CLI  ·  Examples  ·  Docs  ·  Contributing

Story Skills gives agents a shared project format for fiction: the story bible, characters, worldbuilding, plot arcs, scenes, continuity state, promises and payoffs, and chapter drafts. Everything is plain markdown with YAML frontmatter, packaged as Agent Skills and as Codex and Claude Code plugins.

The companion story CLI treats the story bible as a checkable contract. Its continuity engine finds dead characters who reappear, payoffs that land before their setup, and stale story state, before a reader does. Read why it works this way.

Quick start

Writing in claude.ai without a terminal? Writers: start here shows how to upload a skill as a zip.

Claude Code. Type these inside a Claude Code session, not a shell:

/plugin marketplace add danjdewhurst/story-skills
/plugin install story-skills@story-skills

Codex

codex plugin marketplace add danjdewhurst/story-skills
codex plugin add story-skills@story-skills

Any other agent that supports SKILL.md can use the Agent Skills CLI:

npx skills add danjdewhurst/story-skills   # or: bunx skills add danjdewhurst/story-skills

Then ask your agent to "Start a new story".

• Install the skills covers the other agents, including GitHub Copilot, Cursor, Windsurf, Gemini CLI, and OpenCode.
• Let your agent install it has a prompt that installs the skills for you.
• New to Story Skills? Getting started walks through a first session. The documentation index links every guide.

The continuity engine

Language models are weak at long-range consistency, and prompting does not fix that. Story Skills makes it deterministic. Character deaths, promises and payoffs, open questions, scene casts, and object and knowledge state live in frontmatter. story continuity reports contradictions the way a compiler reports type errors.

examples/the-unraveled-thread/ is a deliberately broken mystery. Every file is well formed, so it passes story validate and story links, but the story does not hold together:

$ story continuity examples/the-unraveled-thread
Continuity check failed: 4 errors, 3 warnings, 0 dismissed
error: chapters/chapter-04.md lists edran-vale, who died in chapter-02; move posthumous appearances to mentions
error: continuity/promises/the-broken-compass.md pays off in chapter-02 before it is planted in chapter-03
error: continuity/questions/who-burned-the-mill.md resolves in chapter-02 before it is introduced in chapter-03
error: continuity/state.md knowledge-state[0] references missing chapter chapter-05
warning: chapters/chapter-03.md POV character nessa-thorn is not listed in characters [pov-not-in-cast]
warning: continuity/promises/the-sealed-letter.md was planted in chapter-01, 3 chapters ago, and has no payoff yet [promise-unpaid]
warning: continuity/state.md object-state[0] status active conflicts with worldbuilding/artifacts/vales-compass.md status destroyed [state-status-conflict]

Each finding names its file and reproduces exactly, and CI asserts this output on every commit. Intentional flashbacks and posthumous appearances stay legal through the chapter mentions field. Findings listed in continuity/exemptions.md are reported as dismissed. story doctor and story next turn the same checks into repair actions.

Skills

Most books move through the skills roughly in this order. research, scene-craft, voice-style, verse-craft, and editorial-review are used whenever they are needed rather than at one fixed point. story-maintenance runs underneath all of them, and series-continuity starts the next book. The Skills catalogue has the full details and how the skills hand work to each other.

The table lists the skills in the same order, with what each one does and a request that starts it.

line-editing owns the prose pass. For general writing checks as well, add better-writing with npx skills add forjd/better-writing.

Companion CLI

The optional story CLI handles deterministic project maintenance, and the skills handle the creative work. The CLI needs Node 18 or newer and has no runtime dependencies:

npx story-skills --help
npm install -g story-skills   # then: story --help (Windows too)

Without Node, install the standalone binary with Homebrew on macOS or Linux. Releases after 0.17.0 also attach a binary for macOS, Linux, and Windows to the releases page:

brew install danjdewhurst/tap/story-skills   # then: story --help

Check a downloaded archive against the release's checksums file before you run it. Getting started covers every install route, the checksum steps, and running the CLI from a clone.

These are the commands writers use most:

Other build formats are markdown, docx, shunn, print (a paged HTML interior for Paged.js, WeasyPrint, or Prince, or a PDF with --pdf), narration, codex, metadata, fountain, twee, and ink. The CLI reference lists every command and option.

The CLI only maintains the project. Agents write story content to markdown files and never create project-local build or generator scripts.

Import an existing manuscript

Most writers start with a draft, not a blank page. story import builds a project from one:

story import draft.md --title "The Lost Coast" --genre mystery
story import brouillon.md --title "La Côte perdue" --language fr

It splits the manuscript on chapter headings, or imports a folder of chapter files, and builds the full project with word counts and registries. Import, export, and builds covers the options, including --force.

How it works

Every story element is a markdown file with YAML frontmatter. The skills cross-reference those files to keep the project consistent.

• story.md is the bible that every skill reads. Its schema-version: 2 field lets the CLI reject incompatible formats.
• Entity files use kebab-case identifiers, such as sera-voss or chapter-01. The CLI takes the id from the name, and transliterates Cyrillic and Greek names. A name in a script with no transliteration, such as 李明, needs an id from story add --id. Names themselves can use any script.
• _index.md files are the registries for each domain.
• Relationships are bidirectional.
• Scene records and continuity state keep character knowledge, object ownership, and setups and payoffs in files, so they carry over between sessions.

my-story/
├── story.md                  # Story bible: title, genre, themes, POV, tense
├── style-sheet.md            # Voice, house spellings, and watch words
├── characters/
│   └── _index.md             # Character registry
├── worldbuilding/
│   ├── _index.md             # World overview
│   ├── locations/
│   ├── systems/
│   ├── factions/
│   └── artifacts/
├── plot/
│   ├── _index.md             # Arc overview
│   ├── arcs/
│   └── timeline.md
├── scenes/
│   └── _index.md             # Machine-readable scene registry
├── continuity/
│   ├── state.md              # Character, object, and knowledge state
│   ├── questions/
│   │   └── _index.md
│   ├── promises/
│   │   └── _index.md
│   └── clues/
│       └── _index.md
├── glossary/
│   ├── _index.md
│   └── terms/
└── chapters/
    └── _index.md             # Chapter registry

Some files appear only when needed: matter/ for front and back matter, research/ for research notes, progress.md for the session log, and continuity/exemptions.md for dismissed findings. The Project format reference and schemas/story.schema.json define the contract.

Examples

Complete books made with Story Skills:

• The Cormorant Tide
• Pippa and the Borrowed Star, a children's Christmas story

Example projects in this repository:

Writing in other languages covers what works in each language and script.

Write a book with pull requests

A story project with deterministic checks is one an agent can advance unattended. The templates/github/ workflows turn a story repository into a self-drafting book:

• story-checks.yml runs story check and story report --actionable on every push to main and every pull request, so a chapter PR with a continuity contradiction fails its checks. Mark the story-checks job as a required status check to block the merge.
• draft-next-chapter.yml runs Claude Code on a schedule. It drafts the next chapter within word, turn, and spend budgets, then opens a pull request for review. The agent cannot push.
• review-copy.yml publishes an HTML review copy to GitHub Pages, and manuscript-note.yml gives readers an issue form for notes on exact paragraphs.

Copy the workflows into .github/workflows/, add an ANTHROPIC_API_KEY secret for the drafting workflow, and set Settings > Pages > Source to GitHub Actions for the review copy. GitHub Pages sites are public unless your plan supports private Pages. For a private manuscript, see keeping the manuscript private. Automation and CI covers the rest, including the note form's label.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and the Code of Conduct. User-visible changes are listed in the changelog. The development guide covers the repository layout, the CLI, tests, and releases.

bun install
bun run test
bun run check:metadata

The evals/ harness regression-tests the writing skills against seeded briefs and known traps. See evals/README.md.

License

Story Skills is released under the MIT License.