worldbuilding

Files (10)

• SKILL.md
• artifact-template.md · references/
• calendars.md · references/
• economy-logistics.md · references/
• faction-template.md · references/
• location-template.md · references/
• maps-and-routes.md · references/
• naming-languages.md · references/
• system-template.md · references/
• world-element-types.md · references/

SKILL.md (first lines)

# 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:

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

## 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:

From danjdewhurst/story-skills, MIT.

More from danjdewhurst/story-skills