Story Skills

by danjdewhurst• 373•• Scanned•Claim this listing•Request removal

Content & Writingagent skillsai agentsclaude code pluginclaude skillscodex

Agent Skills for end-to-end story writing in markdown, packaged as Codex and Claude Code plugins.

Story Skills is an open-source agent skill by danjdewhurst, written mainly in JavaScript, with 373 GitHub stars and the MIT license. Its code was last updated Nov 1, 2026. The latest npm release is story-skills 0.25.0, published Nov 12, 2026, with 472 downloads last week.

about SKILL.md / README security reviews

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/hero-dark.svg"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/hero-light.svg" alt="Story Skills" width="560"> </picture> Plan, track, and draft fiction in markdown, with a continuity checker that catches mistakes before readers do. <a href="https://www.npmjs.com/package/story-skills"><img src="https://img.shields.io/npm/v/story-skills?style=flat-square&color=7c3aed&label=npm" alt="npm version"></a> <a href="https://www.npmjs.com/package/story-skills"><img src="https://img.shields.io/npm/dm/story-skills?style=flat-square&color=7c3aed&label=downloads" alt="npm downloads a month"></a> <a href="https://github.com/danjdewhurst/story-skills/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/danjdewhurst/story-skills/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a> <a href="docs/getting-started.md#install-the-story-cli"><img src="https://img.shields.io/node/v/story-skills?style=flat-square&color=7c3aed" alt="Node version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7c3aed?style=flat-square" alt="MIT license"></a> <a href="https://scorecard.dev/viewer/?uri=github.com/danjdewhurst/story-skills"><img src="https://img.shields.io/ossf-scorecard/github.com/danjdewhurst/story-skills?style=flat-square&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a> <a href="https://github.com/danjdewhurst/story-skills/stargazers"><img src="https://img.shields.io/github/stars/danjdewhurst/story-skills?style=flat-square&color=7c3aed" alt="GitHub stars"></a> <a href="#quick-start">Quick start</a>  ·  <a href="#the-continuity-engine">Continuity engine</a>  ·  <a href="#skills">Skills</a>  ·  <a href="#companion-cli">CLI</a>  ·  <a href="#examples">Examples</a>  ·  <a href="docs/README.md">Docs</a>  ·  <a href="https://github.com/danjdewhurst/story-skills/blob/main/CONTRIBUTING.md">Contributing</a> </div>

Prefer an app? Plothold is a web app built on Story Skills by the same maintainer, with a writing partner and the same continuity engine. It is paid, with a free trial, and stores your book on its servers, as its privacy policy explains.

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.

<table> <tr> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-markdown.svg" width="40" height="40" alt=""> Plain markdown Every character, place, scene, and chapter is a markdown file with YAML frontmatter. Diff it, branch it, and open it in any editor. </td> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-skills.svg" width="40" height="40" alt=""> 24 skills, premise to print From testing a spark of an idea to the query letter and the print interior, in Claude Code, Codex, or any agent that reads <code>SKILL.md</code>. </td> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-continuity.svg" width="40" height="40" alt=""> A continuity compiler Deaths, promises, open questions, and object and knowledge state live in frontmatter, so contradictions show up like type errors. </td> </tr> <tr> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-languages.svg" width="40" height="40" alt=""> Any language Write in any language and script. Builds set right-to-left scripts and vertical Chinese, Japanese, and Korean text. </td> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-builds.svg" width="40" height="40" alt=""> Builds for every reader EPUB, DOCX, a Shunn manuscript, a print interior, an HTML review copy, a screenplay, and Twine and ink, all from one project. </td> <td width="33%" valign="top"> <img src="https://raw.githubusercontent.com/danjdewhurst/story-skills/main/assets/readme/icon-pull-requests.svg" width="40" height="40" alt=""> A book by pull request GitHub Actions templates draft the next chapter on a schedule and fail a pull request that breaks continuity. </td> </tr> </table>

Quick start

Writing in claude.ai without a terminal? Writers: start here shows how to upload a skill as a zip. To skip setup entirely, Plothold is a paid, hosted app built on 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

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, and the documentation website has the same pages with search.

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.

Prefer an app?

Plothold is a web app for writing fiction, built on Story Skills, for writers who would rather not use a terminal or a coding agent. You chat with a writing partner on one side, and the book updates on the other: chapters, cast, world, open threads, and a story check powered by the same continuity engine. It runs in the browser on a laptop or a phone, imports drafts from Word, and exports EPUB, PDF, and Word.

Plothold is a paid product made by the Story Skills maintainer, and its subscriptions fund Story Skills development. It has a free trial. Your book is stored on Plothold's servers; its privacy policy says how it is handled. Story Skills itself stays free and MIT-licensed, and Plothold is a separate product built on top of it.

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.

Skill	Try saying
premise-workshop<br>Tests a spark as a premise, then hands off to `story init`	"Is there a novel in this idea?"
story-init<br>Scaffolds the story bible, folders, and registries	"Start a new story"
character-management<br>Builds character profiles, relationships, and arcs	"Create a character"
worldbuilding<br>Builds locations, systems, factions, and invented terms	"Design a magic system"
plot-structure<br>Plans arcs with three-act, hero's journey, Save the Cat, and other structures	"Create a plot arc"
theme-craft<br>Finds the controlling idea, the moral argument, and the motifs	"What's my story really about?"
genre-craft<br>Checks genre conventions, such as mystery fair play, romance beats, and horror	"Plan a fair-play mystery"
research<br>Checks the real-world facts a story relies on, with sources and confidence	"Fact-check the sailing in chapter 4"
chapter-writing<br>Drafts chapters from an outline and the story context	"Write the next chapter"
discovery-drafting<br>Drafts from a story kernel, then reconciles the bible after each chapter	"I want to discovery-write"
scene-craft<br>Checks scene structure, dialogue, POV, and chapter openings	"Does this chapter breathe?"
voice-style<br>Keeps the style sheet: spellings, dialogue punctuation, and character voices	"Set up a style sheet for this book"
verse-craft<br>Writes and scans verse, with stresses and rhyme schemes shown	"Does this limerick scan?"
interactive-fiction<br>Plans branching books: choice graphs, endings, and Twine and ink builds	"Plan where the branches rejoin"
revision-continuity<br>Revises drafts and audits continuity and character state	"Continuity-check chapter 3"
line-editing<br>Edits lines with a reason for each change, and checks that character voices differ	"Line edit chapter 3. Everyone sounds the same."
reader-panel<br>Runs simulated persona reads before human readers see a chapter	"Give me a simulated beta read of chapters 1 to 5"
feedback-triage<br>Turns alpha and beta reader feedback into a revision plan	"Triage the beta feedback"
editorial-review<br>Handles sensitivity reads, permissions, the AI-use statement, and editor rounds	"I'm quoting a song lyric as my epigraph. What do I need?"
submission<br>Checks submission readiness and drafts the query letter, synopsis, and comp titles	"Help me query agents"
publishing<br>Self-publishing production: retailer metadata, ISBNs, EPUB and print interiors, and pricing	"Get my book ready for KDP and IngramSpark in 6x9"
adaptation<br>Carries the story into audiobook, screenplay, picture-book, comics, and translated editions	"Make a narration script so I can audition narrators"
series-continuity<br>Starts sequels and prequels, and checks shared canon across books	"Start a prequel to The Last Ember"
story-maintenance<br>Runs the deterministic CLI checks: validation, continuity, reports, and exports	"Validate my story project"

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:

Command	Purpose
`story init "The Last Ember"`	Scaffold a story project
`story import draft.md --title "The Lost Coast"`	Split an existing manuscript into a project and list its recurring names
`story collect .`	Rewrite a short-story collection's chapters from the story projects its `stories` list names
`story add character "Sera Voss"`	Create a file for a character, place, scene, promise, clue, or other entity
`story rename character sera-voss "Sera Vale"`	Rename an entity and update its references in frontmatter and links
`story check [path] --strict`	Run validation, link checks, and continuity in one scan; `--strict` also fails on warnings
`story list chapters --where status=draft`	List the entities whose frontmatter matches a filter
`story wordcount [path] --write`	Count chapter words and update the chapter registry
`story next [path]`	Recommend the next writing or maintenance action
`story knowledge sera-voss --at chapter-03`	Show what a character knew at a chapter
`story context chapter-03 --budget 6000`	Pack the drafting context for a chapter into a token budget
`story prose [path]`	Lint prose for filter words, adverbs, and style-sheet spellings
`story progress [path] --log`	Report words against targets and the deadline
`story export [path] --out dist/manuscript.md`	Combine front matter, chapters, and back matter into one manuscript
`story build [path] --format epub`	Build an EPUB with the cover, publishing metadata, and accessibility metadata
`story build [path] --format html`	Build a review copy whose paragraphs carry anchors such as `ch03-p12`
`story apply edited.docx --ref sent-to-editor-1`	Write an editor's returned Word file back into the chapters' prose, keeping your own edits since you sent it

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 reads markdown, plain text, a Word .docx, an OpenDocument .odt, or an .epub. 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.

<details> <summary>The project layout that <code>story-init</code> creates</summary>

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

</details>

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:

the-last-ember A fantasy with a magic system, a plot arc with foreshadowing, and a drafted chapter