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)
   • Pronunciation, if the name is invented or easily misread (pronunciation: "KEL-ah-mar")
5. Before settling an invented name, run story names '{Candidate}' to catch clashes and look-alikes (see references/naming-languages.md)
6. Create it with story add location '{Location Name}' --type '{type}' when the CLI is available (add --region, --population, --controlled-by, and --character 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
7. Without the CLI, write the file from references/location-template.md to worldbuilding/locations/{name-kebab}.md
8. Leave the locations table in worldbuilding/_index.md to story reindex ., even without the CLI; never add a row by hand
9. 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
10. 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.

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.