/worldbuilding

name: worldbuilding
description: This skill should be used when the user asks to "create a location", "add a location", "magic system", "political system", "build the world", "add culture", "world history", "technology system", "religion", "economy", "map", "travel times", "routes", "calendar", "moons", "seasons", "naming language", "conlang names", "trade routes", "supply lines", "magic cost", "add a glossary term", "glossary", "invented word", or wants to develop any aspect of a story's world and setting. NOT for a glossary for translators (use adaptation).

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"`)

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`, `--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` 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.

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