story-skills

✨ 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, character files, worldbuilding notes, factions, artifacts, plot arcs, scene state, continuity questions, promises/payoffs, timelines, and chapter drafts. Everything is plain markdown with YAML frontmatter, packaged as standard Agent Skills with Codex and Claude Code plugin support.

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

---

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 (type these inside a Claude Code session, not a shell)
/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.

📦 Installation

# Add the marketplace
codex plugin marketplace add danjdewhurst/story-skills

# Install the plugin
codex plugin add story-skills@story-skills

For local skill authoring without a plugin install:

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

# Or install to a specific repo as repo-scoped skills
cp -r story-skills/skills/* .agents/skills/

Codex detects repo and user skills automatically. The plugin install is still the recommended path for this bundle.

# Add the marketplace
/plugin marketplace add danjdewhurst/story-skills

# Install the plugin
/plugin install story-skills@story-skills

VS Code with Copilot discovers skills from multiple directories:

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

# Copy skills to your project (any of these work)
cp -r story-skills/skills/* .github/skills/
cp -r story-skills/skills/* .agents/skills/

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

Skills can activate when your request matches a skill description, or you can invoke them manually.

Cursor supports the SKILL.md standard:

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

cp -r story-skills/skills/* .agents/skills/

Windsurf discovers skills from workspace and global directories:

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

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

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

Cascade can invoke a matching skill automatically. You can also use @skill-name to invoke one directly.

Gemini CLI supports the same SKILL.md format via the Agent Skills standard:

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

# Or install a specific skill
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/story-init
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/character-management
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/worldbuilding
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/plot-structure
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/chapter-writing
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/revision-continuity
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/series-continuity
gemini skills install https://github.com/danjdewhurst/story-skills.git --path skills/story-maintenance

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

Gemini discovers the skills and can activate them when your request matches a skill description.

The skills use the same SKILL.md format that OpenCode supports natively:

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

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

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

OpenCode also searches common skill paths such as .claude/skills/, so compatible project-level skills can be discovered automatically.

These skills follow the open Agent Skills standard: SKILL.md files with YAML frontmatter. If your agent supports the Agent Skills CLI, install the bundle directly:

npx skills add danjdewhurst/story-skills

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

Use --skill <name> to install only specific skills, or --agent <name> to target a supported agent. You can also copy the skill folders into any compatible agent's skills directory.

For non-agent use:

• Claude.ai / ChatGPT Projects — add the SKILL.md and reference files as project knowledge
• Any LLM API — include skill content in system prompts
• Manual use — the templates, workflows, and story structure are model-agnostic

🛠️ Skills

Skill	What it does	Try saying
story-init	Scaffolds the story bible, folders, and registries	"Start a new story"
character-management	Creates character profiles with relationships, traits, arcs, and family trees	"Create a character"
worldbuilding	Builds locations and systems: magic, politics, technology, religion, and more	"Design a magic system"
plot-structure	Plans arcs with structures like three-act, hero's journey, Save the Cat, and kishotenketsu	"Create a plot arc"
chapter-writing	Drafts chapters through an outline-first workflow that pulls from story context	"Write the next chapter"
revision-continuity	Revises drafts, audits continuity, and keeps character state, timeline, and arc changes consistent	"Continuity-check chapter 3"
series-continuity	Starts sequels and prequels as linked projects, carries characters and world forward, and checks shared canon across books	"Start a prequel to The Last Ember"
story-maintenance	Runs deterministic CLI checks for validation, continuity, reports, indexing, links, word counts, import, and export	"Validate my story project"

For stronger prose, pair chapter-writing with 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 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

The CLI needs Node 18 or newer.

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.

Command	Purpose
story init "The Last Ember"	Scaffold a story project with the standard markdown layout
story add character "Sera Voss"	Create entity files for characters, locations, systems, factions, artifacts, arcs, chapters, scenes, questions, promises, and glossary terms
story rename character sera-voss "Sera Vale"	Rename an entity and update kebab-case references
story remove promise old-setup	Remove an entity and scrub metadata references
story migrate [path]	Upgrade a project to the current schema
story validate [path]	Check required files, schema version, YAML frontmatter, registries, and word-count warnings
story reindex [path]	Rebuild registry tables from the current markdown files
story wordcount [path] --write	Count chapter prose and update chapter frontmatter plus the chapter registry
story links [path]	Check character, location, chapter, and arc cross-references/backlinks
story continuity [path]	Check deterministic continuity contracts: deaths, promises/payoffs, questions, casts, and durable state