danjdewhurst/story-skills/worldbuilding

Worldbuilding

Overview

Create and manage world elements for a story project. Locations, systems (magic, politics, technology, etc.), factions, and artifacts are stored as markdown files in the worldbuilding/ directory with YAML frontmatter, and glossary terms for the world's invented words in glossary/terms/. All elements cross-reference characters and other story elements.

Prerequisites

A story project must already exist (created via the story-init skill). Verify by checking for story.md in the project root.

Creating a Location

1. Read story.md for genre, era, and tone context
2. Read worldbuilding/_index.md for existing locations and systems
3. Ask for the location's name and type (city, fortress, wilderness, etc.)
4. Build the location through conversation, covering:

• Physical description and atmosphere
• History relevant to the story
• Culture and customs of inhabitants
• Notable features characters will interact with
• Current state at story's timeline
• Routes to other locations: travel time in hours and mode (see references/maps-and-routes.md)
• Geography, when the story has a map or known distances: coordinates on the story's map, or distances to other locations (see references/maps-and-routes.md)
• Pronunciation, if the name is invented or easily misread (pronunciation: "KEL-ah-mar")

1. Before settling an invented name, run story names '{Candidate}' to catch clashes and look-alikes (see references/naming-languages.md)
2. Create it with story add location '{Location Name}' --type '{type}' when the CLI is available (add --region, --population, --controlled-by, --character, and --coordinates x,y as known); it writes worldbuilding/locations/{name-kebab}.md and lists it in worldbuilding/_index.md. Then fill the body from references/location-template.md
3. Without the CLI, write the file from references/location-template.md to worldbuilding/locations/{name-kebab}.md
4. Leave the locations table in worldbuilding/_index.md to story reindex ., even without the CLI; never add a row by hand
5. If notable characters are listed, verify those character files exist and add this location's kebab-case identifier to each character file's locations frontmatter list
6. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

Maps, Routes, and Travel

Record travel between locations as routes on the location file, not in prose notes, so the CLI can check it:

routes:
  - to: harbor-district
    hours: 1.5
    mode: on foot
  - to: saltmarsh-fort
    hours: 9
    mode: coach

• to is a location id; story links . checks it exists.
• A route is two-way unless the other location declares its own route back (for example, uphill slower than down).
• story continuity . errors when a character appears in two dated scenes at locations joined by a route and the story time between them is shorter than the route's hours.
• story diagram locations prints the route network as a Mermaid map-graph with edges labelled in hours; add --out dist/locations.mmd to save it. Use it to spot unreachable places and implausible shortcuts.

Use the travel speeds table in references/economy-logistics.md to set plausible hours, and references/maps-and-routes.md for the full workflow.

Distances and travel modes

When the user has a map or knows how far apart places are, record geography instead of, or as well as, route hours. Ask which distance unit the world uses (miles, km, leagues, days' walk) and never assume Earth. In story.md, list how people travel:

distance-unit: leagues
map-scale: 4
travel-modes:
  - mode: on foot
    speed: 1
    per-day: 8
  - mode: horse
    speed: 3
    per-day: 15

• speed is distance units an hour while moving; per-day (optional) is the most one day of travel covers.
• map-scale is how many distance units one map unit spans. Give each location coordinates: [x, y] read off the user's map (squares, centimetres, or pixels), or distances to other locations (- to: greyhaven then distance: 30), or both. A listed distance wins over the straight line on the map.
• On each scene that follows a journey, set travel-hours and travel-mode (one of the modes). story continuity . warns (travel-too-far) when the hours cannot cover the distance from the previous scene at that mode's speed, or at the fastest mode when the scene names none. It judges only the characters who were in both scenes.
• Nothing is checked until story.md lists at least one travel mode.

Creating a System

1. Read story.md for genre and themes context
2. Read worldbuilding/_index.md for existing systems
3. Identify the system type and consult references/world-element-types.md for the relevant prompts. For calendars, naming languages, economies, and magic costs, also use references/calendars.md, references/naming-languages.md, and references/economy-logistics.md
4. Build the system through conversation, addressing the key questions for that type
5. Create it with story add system '{System Name}' --type '{type}' --prevalence '{prevalence}' when the CLI is available (the type and prevalence values are in references/system-template.md); it writes worldbuilding/systems/{name-kebab}.md and lists it in worldbuilding/_index.md. Then fill the body from references/system-template.md
6. Without the CLI, write the file from references/system-template.md to worldbuilding/systems/{name-kebab}.md
7. Leave the systems table in worldbuilding/_index.md to story reindex .; never add a row by hand
8. Cross-reference with characters who interact with the system (e.g., magic-users for a magic system)
9. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

Creating A Faction

Use story add faction '{Faction Name}' --type '{family|guild|government|military|religion|company|community|criminal|other}' when the CLI is available. Otherwise create worldbuilding/factions/{name-kebab}.md with frontmatter fields name, type, status, members, locations, and tags.

Cover:

• Purpose and ideology
• Power base, resources, and territory
• Important members
• Conflicts and pressure points

Then:

1. Save to worldbuilding/factions/{name-kebab}.md
2. Leave the Factions table in worldbuilding/_index.md to story reindex .; never add a row by hand
3. If members are listed, verify those character files exist
4. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

Creating An Artifact

Use story add artifact '{Artifact Name}' --type '{object|weapon|document|technology|relic|symbol|resource|other}' when the CLI is available. Otherwise create worldbuilding/artifacts/{name-kebab}.md with frontmatter fields name, type, status, owner, location, and tags.

Cover:

• Description and recognition details
• Function, constraints, and costs
• History and prior owners
• Current owner/location state

Then:

1. Save to worldbuilding/artifacts/{name-kebab}.md
2. Leave the Artifacts table in worldbuilding/_index.md to story reindex .; never add a row by hand
3. If an owner or location is listed, verify those files exist and cross-reference back
4. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

Adding A Glossary Term

Record an invented word, title, rank, or concept that the prose must spell and use the same way every time as a glossary term in glossary/terms/.

1. Read glossary/_index.md for the existing terms, then run story names '{Term}' to catch a clash with another name or term
2. Use story add term '{Term}' --category '{person|place|faction|artifact|concept|term|other}' when the CLI is available, with --alias '{Variant}' once for each accepted variant; it writes glossary/terms/{term-kebab}.md and lists it in glossary/_index.md. Otherwise create the file with frontmatter fields term, category, and aliases, and leave the glossary/_index.md table to story reindex .
3. Fill ## Definition (what it means in the story) and ## Usage Notes (spelling, capitalisation, who uses it, and what it never means). Add a pronunciation when the term is invented or easily misread
4. When the term's capitalisation or hyphenation is a house-style decision, record it in style-sheet.md too (see the voice-style skill)
5. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

A glossary for translators belongs to the adaptation skill, which adds a ## Translations section to these term files.

Updating World Elements

1. Read the existing file
2. Make the requested changes. If a location or faction changes partway through the story (a city falls, a guild disbands), add a progression instead of editing the opening value (see Changes Over the Story)
3. If cross-references changed, update the linked files
4. Rename an element with story rename (see references/naming-languages.md). Change its type or status in its own file only: the worldbuilding/_index.md tables pick it up at the next story reindex ., so never edit their rows
5. When CLI access is available, run story reindex ., story wordcount . --write, and story check .

Changes Over the Story

Location and faction files describe the world as the story opens. Record a later change as a progression, so drafting an early chapter does not see what happens in a late one:

progressions:
  - from: chapter-10
    field: status
    value: occupied
  - from: chapter-10
    field: controlled-by
    value: lord-maren

• from is the first chapter where the new value holds. It may be a planned chapter-NN with no file yet
• field is a kebab-case single-value field, existing (status, controlled-by, region) or new (ruler, population-note). List fields (notable-characters, routes, coordinates, distances, members, locations, tags) cannot change this way
• value is one value. A faction's type and status must stay within their allowed values
• Keep entries in story order, and read the progressions up to the chapter being drafted before describing the place or faction in it
• Artifacts and systems do not take progressions; track an artifact's changes with object-state and scene state-changes (see the revision-continuity skill)
• The body of the file is prose for the writer. Describe a change in story terms ("from Festival night the city is occupied"), and do not name progressions or other frontmatter fields there

After adding or editing progressions, run story reindex ., story wordcount . --write, and story check ..

Cross-Referencing

• Locations reference characters via notable-characters in frontmatter
• Characters reference locations via locations in frontmatter
• Factions reference character members and locations
• Artifacts reference an owner character or faction and a current location
• Systems reference practitioners via character tags
• Location routes reference other locations by id
• Location distances reference other locations by id
• Invented names across characters, locations, systems, factions, artifacts, and glossary terms may carry a pronunciation; story build --format narration gathers them into a pronunciation guide for audiobook narrators
• When a location is used in a chapter, the chapter's frontmatter locations field links back
• Keep the worldbuilding/_index.md world overview section current as elements are added

CLI Maintenance