Works with Claude Code, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenAI Codex, OpenCode, and any agent that supports the SKILL.md standard.

🚀 Quick Start

# Claude Code — install in two commands
/plugin marketplace add danjdewhurst/story-skills
/plugin install story-skills@story-skills

# Codex — install in two commands
codex plugin marketplace add danjdewhurst/story-skills
codex plugin add story-skills@story-skills

Then just say "Start a new story" and the agent takes it from there.

✍️ Highly Recommended: Better Writing

For stronger chapter prose, revision passes, and less generic AI-written text, we highly recommend installing forjd/better-writing alongside Story Skills. It adds context-aware prose editing, voice calibration, AI-writing tell checks, and final pre-flight review.

npx skills add forjd/better-writing

Or with Bun:

bunx skills add forjd/better-writing

Story Skills works without it, but agents should use better-writing when it is available for chapter drafting, revision, and final prose polish.

📦 Installation

# 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 auto-activate when your request matches a skill's description or can be invoked 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 auto-invokes skills when your request matches a skill's description, or use @skill-name to invoke manually.

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

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

Gemini will auto-discover the skills and activate them when your request matches a skill's description.

Codex uses the same SKILL.md format via the Agent Skills standard:

# 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 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, but the plugin install is recommended for this bundle.

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 .claude/skills/ paths, so project-level Claude skills are automatically discovered.

These skills follow the open Agent Skills standard (SKILL.md with YAML frontmatter). They work with any compatible agent — just copy the skill folders to your 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 best prose quality, pair chapter-writing with better-writing.

📁 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/
├── plot/
│   ├── _index.md             # Arc overview
│   ├── arcs/
│   └── timeline.md
└── chapters/
    └── _index.md             # Chapter registry

⚙️ How It Works

Every story element is a markdown file with YAML frontmatter. Skills cross-reference each other to keep your story consistent:

• story.md is the top-level bible read by all skills
• 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

📖 Example

Explore examples/the-last-ember/ — a complete fantasy story with three characters, two locations, a magic system, a plot arc with foreshadowing tracking, and a first chapter with full prose.

🚢 Releasing

Claude Code uses .claude-plugin/plugin.json as the Claude plugin version source. Codex uses .codex-plugin/plugin.json as the Codex plugin version source. Bump both versions for every published change so installed users receive updates; keep marketplace entries unversioned to avoid duplicate version state.

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 this repo-root plugin without duplicating the skills/ files.

📄 License

MIT