docs(skill): add rules-writing conventions

Add rules.md covering document structure, theme/players/time header, icon-first mentions, veteran-first prose, and a closing timestamp. Link it from SKILL.md.
2026-10-24 16:51:59 +08:00
parent 2ba6ed74c7
commit ae36125af0
2 changed files with 87 additions and 1 deletions
@@ -0,0 +1,82 @@
+# 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:
+
+```markdown
+## 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.
+
+```markdown
+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:
+
+```markdown
+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:
+
+```markdown
+---
+
+*2026-10-24*
+```