story-skills

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. A book can be written in any language: set language in story.md and the skills draft and edit in it, while the CLI counts, checks, and typesets for it (Writing in other languages).

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

Skill	What it does	Try saying
premise-workshop	Turns a spark into a tested premise: what-ifs, logline tests, premise and count