danjdewhurst/story-skills

---

Built on the open Agent Skills standard. Install it as a Codex or Claude Code plugin, with the Agent Skills CLI, or copy the skills/ folders into any agent that supports SKILL.md.

🚀 Quick Start

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

# Claude Code plugin
/plugin marketplace add danjdewhurst/story-skills
/plugin install story-skills@story-skills

For compatible SKILL.md agents, you can also install the bundle with the Agent Skills CLI:

npx skills add danjdewhurst/story-skills

# Or with Bun
bunx skills add danjdewhurst/story-skills

Then ask “Start a new story” to scaffold the project.

🔎 The Continuity Engine

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

examples/the-unraveled-thread/ is a deliberately broken mystery. It passes story validate and story links cleanly — every file is well-formed — but the story itself doesn’t hold together:

$ story continuity examples/the-unraveled-thread
Continuity check failed: 4 errors, 3 warnings
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
warning: continuity/promises/the-sealed-letter.md was planted in chapter-01, 3 chapters ago, and has no payoff yet
warning: continuity/state.md object-state[0] status active conflicts with worldbuilding/artifacts/vales-compass.md status destroyed

These findings are exact, file-addressed, and reproducible — CI asserts them on every commit. Intentional flashbacks and posthumous appearances stay legal via the chapter mentions field. story doctor and story next fold the same checks into prioritized repair actions.

✍️ Highly Recommended: Better Writing

For stronger chapter drafts and revision passes, install forjd/better-writing alongside Story Skills. It adds voice calibration, anti-generic writing checks, and a final prose-quality pass.

npx skills add forjd/better-writing

Or with Bun:

bunx skills add forjd/better-writing

Story Skills works without it, but chapter drafting and revision are better when agents can use better-writing.

📦 Installation

🛠️ Skills

For stronger prose, pair chapter-writing with better-writing.

🧰 Companion CLI

The optional story CLI handles deterministic project maintenance while the skills handle the creative workflow.

bun install
bun run story --help

The package also exposes a Node-compatible bin with no runtime dependencies. It is not on the npm registry yet, so run it straight from GitHub:

npx --yes --package github:danjdewhurst/story-skills story --help

For copied-skill installs, story-maintenance includes a bundled scripts/story.js fallback that agents can run with Node.

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

EPUB and DOCX builds target plain prose: scene-break lines (***, ---) become a * * * separator paragraph, and other markdown structure such as lists or tables is flattened to text. The markdown export keeps chapter text as-is.

For a complete starter transcript, read docs/first-20-minutes.md. For the project contract, read docs/schema-v2.md and schemas/story.schema.json.

Development uses Bun for tests and coverage:

bun run test
bun run test:coverage
bun run test:examples
bun run check:metadata

The copied-skill fallback CLI is generated from the package entrypoint. After changing CLI source, rebuild and check it before release:

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

🤖 Write A Book Via Pull Requests

A story project with deterministic checks is a story project 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, and story continuity on every push and pull request, so a chapter PR cannot merge with a continuity contradiction.
• draft-next-chapter.yml runs Claude Code on a schedule: it asks story next for the next deterministic action, drafts the next chapter with the chapter-writing skill, updates scene records and continuity state, runs the maintenance checks, and opens a pull request for review.

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 per morning.

📥 Import An Existing Manuscript

Most writers don’t start from a blank page. story import reverse-engineers 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), 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.

📁 Project Structure

Running story-init creates this layout:

my-story/
├── story.md                  # Story bible — title, genre, themes, POV, tense
├── 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
├── glossary/
│   ├── _index.md
│   └── terms/
└── chapters/
    └── _index.md             # Chapter registry

⚙️ How It Works

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

• story.md is the top-level bible read by all skills
• story.md includes schema-version: 2 so the CLI can detect incompatible project formats
• Characters, locations, and arcs use kebab-case identifiers (e.g., sera-voss)
• _index.md files serve as registries for each domain
• Relationships and references are maintained bidirectionally
• Scene records and continuity state make character knowledge, object ownership, and setup/payoff tracking durable
• Story content is created directly as markdown; generated build scripts are not part of the project format

📖 Examples

• Read The Cormorant Tide, a full story project generated with Story Skills.
• Explore examples/the-last-ember/ for a complete fantasy example: three characters, two locations, a magic system, a plot arc with foreshadowing, and a drafted first chapter.
• Explore examples/harbor-of-second-light/ for a near-future coastal mystery example with memory technology, a posthumous witness arc, populated continuity state, and a drafted first chapter.
• Explore examples/the-unraveled-thread/ for a deliberately broken project that demonstrates every class of finding the continuity engine reports.

🚢 Releasing

Codex uses .codex-plugin/plugin.json as its plugin version source. Claude Code uses .claude-plugin/plugin.json. Bump both versions for every published change so installed users receive updates; keep marketplace entries unversioned to avoid duplicate version state. Run bun run check:metadata before publishing to confirm package and plugin metadata are aligned.

Distribution metadata lives in .claude-plugin/ for Claude Code and .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