story-maintenance

Validates, reindexes, and exports markdown-based story projects via a deterministic CLI.

Updated Aug 28, 2026
One-click install
npx skills add https://github.com/miyake-san/sogo-agent-platform --skill story-maintenance-miyake-san
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: story-maintenance
Source: https://github.com/miyake-san/sogo-agent-platform/tree/main/skills/experimental/story-maintenance
Command: npx skills add https://github.com/miyake-san/sogo-agent-platform --skill story-maintenance-miyake-san

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Story projects built from many interlinked markdown files (characters, locations, arcs, chapters, scenes, continuity notes) drift out of sync as they grow: registries go stale, cross-references break, and word counts become inaccurate. This Skill runs deterministic maintenance so the mechanical consistency of a story project is checked and repaired without touching creative prose. ## Core Features & Use Cases - Structure validation and link checking: Verify required files exist, frontmatter schemas are valid, and character/location/arc/chapter cross-references include proper backlinks. - Registry rebuilds and word counts: Reindex entity registries after adding or renaming characters, locations, or arcs, and recompute chapter word counts with wordcount --write. - Reports and next actions: Generate project status reports, actionable next-step lists, and doctor diagnostics identifying stale or broken content. - Manuscript export and builds: Export a combined manuscript or build the book as markdown, EPUB, or DOCX into dist/. - Use Case: After drafting three new chapters and renaming a character, run story reindex ., story links ., and story wordcount . --write to bring registries, backlinks, and word counts back into a consistent state. ## Quick Start Ask the assistant to run the story CLI's validate and report commands on your story project folder to check its structure and get a health summary.

Frequently Asked Questions about story-maintenance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate a markdown story project structure?

Run `story validate .` from the story project root. The CLI checks that all required paths exist, frontmatter schemas are correct, and registry indexes link to every entity file, reporting errors and warnings.

How do I fix broken character and location cross-references in a story project?

Run `story links .` to detect missing references and absent backlinks between characters, locations, arcs, chapters, and scenes. Then repair the reported files, or use `story reindex .` to rebuild registries after renames.

What commands does the story CLI provide?

The CLI provides validate, reindex, wordcount, links, report, next, doctor, migrate, add, rename, remove, export, and build. Build supports markdown, EPUB, and DOCX outputs written to the dist directory.

Can I export my story project to EPUB or DOCX?

Yes. Run `story build . --format epub` or `story build . --format docx` to produce book artifacts in the dist folder. Use `story export . --out manuscript.md` for a single combined markdown manuscript.

What if the story CLI is not installed?

The Skill falls back to `bun run story -- <command>` in the repository or the bundled `node scripts/story.js <command>`. If none are available, maintenance is performed manually following the story-init conventions.

Does story maintenance modify my creative writing?

No. The CLI only fixes mechanical consistency such as registries, links, and word counts. It does not overwrite creative prose, and intentional validation warnings are reported rather than silently changed.