Agent Skills for planning, tracking, and drafting fiction in markdown.

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

The companion story CLI treats the story bible as a checkable contract. Its continuity engine catches dead characters walking, payoffs that land before their setup, unfired Chekhov guns, and stale story state, deterministically, before a reader finds them.

Why it works this way: Story Skills: a continuity compiler for AI-written fiction

Quick start

Install the plugin in Codex or Claude Code:

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

# Claude Code (type these inside a Claude Code session, not a shell)
/plugin marketplace add danjdewhurst/story-skills
/plugin install story-skills@story-skills

For any other agent that supports SKILL.md, 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". Per-agent instructions for GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenCode, and others are under More install options.

New to Story Skills? Getting started walks through a first session, and the documentation index links every guide and reference page.

Or let your agent install it

Paste this prompt into your coding agent. It works out which agent it is and uses the matching install method:

Install the Story Skills bundle from https://github.com/danjdewhurst/story-skills.

First, work out which agent you are, then use the matching method below. If a command fails or you can't run it, tell me the exact command to run myself.

- Claude Code: run `claude plugin marketplace add danjdewhurst/story-skills`, then `claude plugin install story-skills@story-skills`. If the `claude` CLI isn't available, tell me to type `/plugin marketplace add danjdewhurst/story-skills` and then `/plugin install story-skills@story-skills` in this session.
- Codex: run `codex plugin marketplace add danjdewhurst/story-skills`, then `codex plugin add story-skills@story-skills`.
- Gemini CLI: run `gemini skills install https://github.com/danjdewhurst/story-skills.git`.
- Any other agent that supports SKILL.md (GitHub Copilot, Cursor, Windsurf, OpenCode, and others): run `npx skills add danjdewhurst/story-skills`, or `bunx skills add danjdewhurst/story-skills` if only Bun is installed. If that doesn't support you, clone the repository to a temporary directory and copy every folder in its `skills/` directory into your skills directory:
  - GitHub Copilot: `.github/skills/` in this project, or `~/.copilot/skills/` globally
  - Cursor: `.agents/skills/` in this project
  - Windsurf: `.windsurf/skills/` in this project, or `~/.codeium/windsurf/skills/` globally
  - OpenCode: `.opencode/skills/` in this project, or `~/.config/opencode/skills/` globally
  - Anything else: your documented skills directory, or `.agents/skills/` in this project

Prefer a project install unless I asked for a global one. If you can't tell which agent you are, ask me before installing. When you're done, tell me what you installed, where it went, and whether I need to restart or reload you for the skills to show up.

The continuity engine

Long-range consistency is what language models are worst at, and prompting can't fix it. Story Skills makes it deterministic: character deaths, promises and payoffs, open questions, scene casts, and durable knowledge and object state live in frontmatter, and story continuity treats contradictions the way a compiler treats type errors.

examples/the-unraveled-thread/ is a deliberately broken mystery. Every file is well-formed, so it passes story validate and story links cleanly, but the story itself doesn't 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]

Every finding is exact, file-addressed, and reproducible, and CI asserts this output on every commit. Intentional flashbacks and posthumous appearances stay legal through the chapter mentions field, and findings listed in continuity/exemptions.md are reported as dismissed. story doctor and story next fold the same checks into prioritized repair actions.

Skills

line-editing owns the prose pass. For general-purpose writing checks as well, add better-writing. It adds voice calibration, anti-generic writing checks, and a final prose-quality pass, and installs the same way:

npx skills add forjd/better-writing

Companion CLI

The optional story CLI handles deterministic project maintenance while the skills handle the creative work. It needs Node 18 or newer and has no runtime dependencies. Run it with npx, or install it globally:

npx story-skills --help
npm install -g story-skills   # then: story --help

To try unreleased changes, run it straight from GitHub with npx --yes --package github:danjdewhurst/story-skills story --help.

Without Node. Releases after 0.17.0 attach a standalone story binary for macOS (Apple silicon and Intel), Linux (x64 and arm64), and Windows (x64). Install it with Homebrew on macOS or Linux, or download the archive for your system from the releases page, check it against the release's story-skills_<version>_checksums.txt, and put story on your PATH (details):

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

The binary is the CLI only, and reports the same story --version as the npm package. The skills still need an agent such as Claude Code or Codex (see Quick start).

From a clone, use bun install and then bun run story -- --help. Copied-skill installs don't need either: story-maintenance bundles a scripts/story.js fallback that agents run with Node.

The CLI is for maintenance only. Agents write story content directly to markdown files and never create project-local build or generator scripts to emit the story.

Create and restructure

Check and repair

Analyze

Publish

Behavior notes:

• Matter pages from matter/ appear in the export and in every build format except Shunn, which is a submission format.
• EPUB and DOCX builds target plain prose: *italic* and **bold** become italic and bold runs, scene-break lines (***, ---) become a * * * separator, and other markdown structure such as blockquotes, lists, and tables is flattened to text. The markdown export keeps chapter text as-is.
• story rename, story move, and story remove update entity ids in frontmatter reference fields and markdown link targets. They never edit prose, so a character called "Port" can be renamed without touching the word "port" in chapter text.
• A command that changes a frontmatter value rewrites only the entries that changed. Comment lines, unchanged entries, and the body keep their exact text, and files whose values don't change are left untouched.

Every command and option is in the CLI reference. For a complete first session, read Getting started. For the project contract, read the Project format reference and schemas/story.schema.json.

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 validate, story links, story continuity, and story report --actionable on every push and pull request, so a chapter PR can't merge with a continuity contradiction.
• draft-next-chapter.yml runs Claude Code on a schedule. It asks story next for the next action, drafts the next chapter with the chapter-writing skill, updates scene records and continuity state, and commits it within word, turn, and spend budgets. The agent cannot push. A second job, on a fresh runner, checks that the commit touches only the story's own markdown and holds no secret, runs the checks, pushes the branch, and opens a pull request for review: ready when the checks pass, a draft listing the failures when they do not. When story next suggests no chapter (the story is revising or complete, or every arc is resolved), it stops without drafting.

Copy both files into .github/workflows/ in the repository that holds your story project, add an ANTHROPIC_API_KEY secret, and review one chapter PR each morning.

GitHub doesn't start story-checks.yml for pull requests opened with the built-in GITHUB_TOKEN, so the draft workflow runs the same checks itself after drafting. Pass a personal access token as github_token if you also want the checks workflow to run on those PRs.

Readers who never open a terminal can review the book too:

• review-copy.yml builds story build --format html on every push to main and publishes it to GitHub Pages. Every paragraph in the review copy carries a label such as ch03-p12, so a note can point at an exact place.
• ISSUE_TEMPLATE/manuscript-note.yml is an issue form that asks readers for that label, the kind of note, and how much it affected their reading. The feedback-triage skill turns those issues into a feedback round.

Copy the workflow into .github/workflows/ and the form into .github/ISSUE_TEMPLATE/, then set Settings > Pages > Source to GitHub Actions. Pages sites are public unless your plan supports private Pages; for a private manuscript, delete the deploy job and share the workflow artifact instead.

Import an existing manuscript

Most writers don't start from a blank page. story import builds a Story Skills project from work in progress:

story import draft.md --title "The Lost Coast" --genre mystery

It splits the manuscript on chapter headings (or imports a directory of chapter files in natural name order, so chapter-2 comes before chapter-10), creates the full project layout with accurate word counts and registries, and prints recurring proper-name candidates so an agent can follow up with story add character and story add location to build out the bible.

--force lets an import reuse an existing directory. It replaces every chapter-NN.md file in chapters/, so stale chapters from an earlier import are removed.

Project structure

Running story-init creates this layout:

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 once you need them: matter/ for front and back matter, research/ for research notes, progress.md for the session log written by story progress --log, and continuity/exemptions.md for dismissed continuity findings.

How it works

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

• story.md is the top-level bible that every skill reads. Its schema-version: 2 field lets the CLI detect incompatible project formats.
• Every entity file is named by a kebab-case identifier, such as sera-voss or chapter-01. It comes from the entity's name, or from story add --id when the name has no ASCII letters or digits; names themselves may be written in any script.
• _index.md files are the registries for each domain.
• Relationships and references are kept bidirectional.
• Scene records and continuity state keep character knowledge, object ownership, and setups and payoffs in files, so they carry over between sessions.

Examples

Complete projects generated with Story Skills:

• The Cormorant Tide
• Pippa and the Borrowed Star, a children's Christmas story (6 chapters, 2,183 words)

Examples in this repository:

• examples/the-last-ember/: a fantasy with three characters, two locations, a magic system, a plot arc with foreshadowing, and a drafted first chapter.
• examples/the-fall-of-the-citadel/: a prequel to The Last Ember, linked with series, book-number, and precedes, that shares characters and places with the first book. Run story series examples/the-last-ember to see the chronology.
• examples/harbor-of-second-light/: a near-future coastal mystery with memory technology, a posthumous witness arc, populated continuity state, and a drafted first chapter.
• examples/the-gull-rock-light/: a short branching story whose chapters carry choices; story build --format twee turns it into a Twine story and --format ink into an ink story.
• examples/the-unraveled-thread/: a deliberately broken project that demonstrates the main kinds of finding the continuity engine reports.

More install options

git clone https://github.com/danjdewhurst/story-skills.git

# User-wide
mkdir -p ~/.agents/skills && cp -r story-skills/skills/* ~/.agents/skills/

# Or repo-scoped
mkdir -p .agents/skills && cp -r story-skills/skills/* .agents/skills/

git clone https://github.com/danjdewhurst/story-skills.git

# Copy skills to your project (either works)
mkdir -p .github/skills && cp -r story-skills/skills/* .github/skills/
mkdir -p .agents/skills && cp -r story-skills/skills/* .agents/skills/

# Or install globally
mkdir -p ~/.copilot/skills && cp -r story-skills/skills/* ~/.copilot/skills/

git clone https://github.com/danjdewhurst/story-skills.git
mkdir -p .agents/skills && cp -r story-skills/skills/* .agents/skills/

git clone https://github.com/danjdewhurst/story-skills.git

# Copy skills to your project
mkdir -p .windsurf/skills && cp -r story-skills/skills/* .windsurf/skills/

# Or install globally
mkdir -p ~/.codeium/windsurf/skills && cp -r story-skills/skills/* ~/.codeium/windsurf/skills/

# Install all skills globally
gemini skills install https://github.com/danjdewhurst/story-skills.git

# Or install a single skill (any folder under skills/)
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/chapter-writing

# Or link locally after cloning
git clone https://github.com/danjdewhurst/story-skills.git
gemini skills link story-skills/skills

git clone https://github.com/danjdewhurst/story-skills.git

# Copy skills to your project
mkdir -p .opencode/skills && cp -r story-skills/skills/* .opencode/skills/

# Or install globally
mkdir -p ~/.config/opencode/skills && cp -r story-skills/skills/* ~/.config/opencode/skills/

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

Development and releasing

To contribute, start with CONTRIBUTING.md and the Code of Conduct. User-visible changes are listed in the changelog. The Development guide covers the repository layout, CLI architecture, tests, and release process in full. Development uses Bun:

bun install
bun run test
bun run test:coverage
bun run test:examples   # also validates every example against schemas/story.schema.json
bun run check:metadata

bun run build:fallback generates the copied-skill fallback CLI from the package entrypoint. After changing CLI source, rebuild it, check it is current, and confirm it runs under Node:

bun run build:fallback
bun run check:fallback
node skills/story-maintenance/scripts/story.js --help

The evals/ harness regression-tests the writing skills. Fixtures seed a drafting brief with known canon and known traps. A dependency-free checker verifies that drafts keep the canon and spring none of the traps, a model runner (requires the claude CLI) drafts through a real model and judges for invented canon, and a pairwise comparison measures the skill against a no-skill baseline. See evals/README.md.

bun run check:evals      # validate fixture schemas
bun run eval:selftest    # checker self-test against known-good drafts
node evals/run-skill.js  # full model run (needs Claude Code credentials)

Every published change needs a new version in package.json, .codex-plugin/plugin.json (Codex's version source), .claude-plugin/plugin.json (Claude Code's), and src/version.js (printed by story --version), so installed users receive updates. Marketplace entries stay unversioned to avoid duplicate version state.

Don't bump these by hand. The release script bumps all four, plus the template STORY_REF pins and the version examples in the docs, moves the Unreleased entries in CHANGELOG.md under the new version (and refuses to run while there are none), rebuilds the fallback, runs the CI checks, commits chore: release X.Y.Z, tags vX.Y.Z, pushes, and creates a GitHub release with generated notes. The tag push runs the Publish workflow, which publishes the package to npm with provenance through trusted publishing. The script requires a clean main that matches origin/main, a logged-in gh, and a version that isn't already on npm:

bun run release patch            # or minor, major, or an explicit version like 1.2.0
bun run release patch --dry-run  # run the checks and print the plan without changing anything

Distribution metadata lives in .claude-plugin/ for Claude Code and in .codex-plugin/ plus .agents/plugins/marketplace.json for Codex. The plugins/story-skills symlink is intentional: Codex marketplace entries must point at a child plugin directory, so the symlink exposes the repo-root plugin without duplicating skills/.

License

MIT