✨ 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.

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

# 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

# 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

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