ttrpg-tools/.agents/skills/tttk-authoring/rules.md

Writing rules documents

A rules document is the markdown printed with :md-print[./rules.md] (see reference.md for the element). It is read at the table, so it is written to be scanned, not studied. These conventions keep it dense and fast to use.

Document structure

Every rules document follows the same five-part skeleton, in order:

1. Briefing — what the game is and what the players are doing.
2. Components — the pieces in play (cards, tokens, sheets, dice).
3. Setup — how to get from the box to the first turn.
4. Game flow — the loop of play, turn by turn.
5. Game end — how the game finishes and who wins.

Use these as ## headings so a reader can jump straight to the part they need.

Theme, players, and time

Open the briefing with one sentence that explains the theme — the fiction the players step into — then state the player count range and the time estimate:

## Briefing

You are rival merchants trading spice across a desert that wants you dead.

**2–4 players · 30–45 minutes**

Icon-first mentions

When a paragraph mentions a concept for the first time, and that concept has an icon under assets/, prefix the concept with the icon. The icon becomes a visual anchor the reader can find without reading the whole sentence.

Spend a :[coin]coin to bribe the :[guard]guard.

Write the icon immediately before the word, with no space: :[coin]coin, not :[coin] coin. Only the first mention in a paragraph gets the icon; later mentions stay plain so the prose does not turn into a wall of icons. See reference.md for the :[name] inline directive.

Veteran-first prose

Write the default text for a veteran player who only needs to refresh their memory: the rule, the number, the trigger. Assume they already know the game.

Everything that is not needed to play — edge cases, worked examples, the reasoning behind a rule, theme and flavour — is look-up material for new players and corner cases. Box it in a GitHub alert so it stays out of the way of the main line:

A :[shield]shield reduces incoming damage by 2.

> [!NOTE]
> Shields do not stack. A character carrying two shields still reduces damage
> by 2, and a shield offers no protection against fire.

Pick the alert type to signal intent: [!NOTE] for clarifications and edge cases, [!TIP] for advice, [!IMPORTANT] for rules that are easy to miss, [!WARNING] / [!CAUTION] for consequences. See markdown.md for the alert syntax.

The test: if a veteran can play correctly from the plain text alone, the split is right. If a rule only exists inside an alert, it belongs in the main text.

Rule timestamp

End every document with a timestamp, so a printed copy can be checked against the current rules:

---

*2026-10-24*