ttrpg-tools/docs/skill-reference-plan.md

tttk skill reference — reorganization plan

Status: implemented. Follows the tttk check work that made docs/reference.md a generated artifact (see docs/check-plan.md §7.11).

Landed: known.ts carries element/role details, inline specs, and dice notation; reference.ts renders them; scripts/generate-reference.ts expands ~ in --out; npm run gen:skill-reference refreshes the skill copy. The skill's reference.md is now generated and byte-identical to docs/reference.md, with the extra content moved to layout.md, yaml-tag.md, csv.md, and markdown.md.

1. Goal

Make the tttk-authoring skill's reference.md a generated file — the same catalog the validator uses — and relocate the authoring content it does not cover into focused companion files. One source of truth (known.ts), no hand-maintained element list, and no content lost in the swap.

2. Current state

The skill (~/.agents/skills/tttk-authoring/) has a hand-written reference.md (~465 lines) and SKILL.md. The repo now generates docs/reference.md from src/cli/validate/known.ts via npm run gen:reference.

What the generated doc already covers:

• Directive syntax (brief)
• Custom elements: table + per-element summary, body, attrs, examples
• Inline directives: icons, :cmd (brief)
• Code block roles: spark-table, declare, file, tag (brief)
• CSV data files (brief)

What only the hand-written skill copy has (the "extra content"):

#	Section	Notes
A	Directive syntax table + container example	richer than generated
B	Per-element prose	md-dice behavior, md-table roll/remix/group, md-deck legacy layer syntax, md-bg fit values, md-border class flags, md-font source values, md-pins behavior, md-commander CSV columns
C	Icon attributes	label, repeat, join, class
D	Column layout	|--- / -|- / --| markers
E	role=declare column semantics	tag/threshold/key/expr
F	YAML tag blocks	data-config, layers, back_layers, fence-line overrides
G	CSV authoring	clean-CSV guidance, label/body, front matter (avoid)
H	Alerts and mermaid	GitHub alerts, mermaid diagrams
I	Dice notation	notation table
J	Validation codes	already duplicated in SKILL.md

3. Target skill layout

tttk-authoring/
├── SKILL.md          # workflow, rules, validation codes, links
├── reference.md      # GENERATED from known.ts — elements, roles, inline, dice, CSV basics
├── layout.md         # column layout
├── yaml-tag.md       # role=tag, data-config, deck layers and backs
├── csv.md            # CSV authoring and front matter
├── markdown.md       # alerts and mermaid
└── examples/         # unchanged

reference.md is the only generated file; the rest are hand-written and linked from SKILL.md.

4. Content mapping

Source	Destination
A directive syntax	generator (reference.ts) — add the part/meaning table + container example
B per-element prose	known.ts details field → rendered into reference.md
C icon attributes	known.ts inline specs → rendered into reference.md
E declare semantics	known.ts RoleSpec.details → rendered into reference.md
I dice notation	known.ts DICE_NOTATION → rendered into reference.md
D column layout	layout.md
F YAML tag blocks	yaml-tag.md
G CSV authoring	csv.md
H alerts and mermaid	markdown.md
J validation codes	dropped — SKILL.md owns the code tables

Decision (recommended): fold B/C/E/I into known.ts rather than a separate components.md. It keeps the generated reference self-sufficient and avoids a second, drifting description of the same elements. The alternative — a hand-written components.md — is rejected because it reintroduces the drift the generator exists to prevent.

5. Generator changes

src/cli/validate/known.ts:

• ElementSpec.details?: string — one paragraph of authoring prose.
• ElementSpec.attrs → optional richer { name, description }[] so the reference can render an attribute table (keep the plain list if not worth it).
• InlineSpec for :[icon] and :cmd with body/attrs/summary/examples.
• RoleSpec.details?: string for declare column semantics.
• DICE_NOTATION: { notation, meaning }[].

src/cli/validate/reference.ts:

• Render details, the attribute table, inline specs, and dice notation.
• Add a Contents TOC.
• Upgrade the directive-syntax section (table + container example).

scripts/generate-reference.ts:

• Expand a leading ~ in --out to os.homedir() so the skill copy can be regenerated cross-platform.

package.json:

• gen:reference — unchanged (writes docs/reference.md).
• gen:skill-reference — gen:reference -- --out ~/.agents/skills/tttk-authoring/reference.md.

6. New skill file outlines

• layout.md — column markers, the -N width suffix, a worked example.
• yaml-tag.md — role=tag shape (tag:, body:, other keys as attrs), fence-line overrides, data-config layer fields (prop/template, pos, font/fontSize, orientation, align, visible), back_layers, and the legacy :md-deck compact layer syntax.
• csv.md — clean-CSV guidance, label/body conventions, group tabs, {{prop}} interpolation, quoting rules, and the discouraged front-matter form.
• markdown.md — GitHub alerts and mermaid (standard markdown, not tttk syntax).

7. SKILL.md changes

• Update the "Reference" section to link reference.md plus the four new files.
• Keep the validation code tables in SKILL.md (they are the agent's quick reference); reference.md no longer carries them.
• Reword "check reference.md when unsure" to point at the right file per topic.

8. Steps

1. Enrich known.ts (details, inline specs, role details, dice notation).
2. Update reference.ts and generate-reference.ts; regenerate docs/reference.md; keep the known.test.ts drift guard green.
3. Extract D/F/G/H from the old skill reference.md into layout.md, yaml-tag.md, csv.md, markdown.md.
4. Regenerate the skill's reference.md with npm run gen:skill-reference.
5. Update SKILL.md links.
6. Verify (§9).

9. Verification

• npm run gen:reference leaves docs/reference.md unchanged (idempotent).
• npx jest passes, including the reference drift guard.
• Diff the old skill reference.md against the new file set and confirm every section in §2's table has a destination — no content silently dropped.
• npx tttk check ./content still runs clean (the catalog changes are documentation-only, but the drift guard protects known.ts).

10. Risks

• Content loss during extraction. Mitigate with the §4 mapping as a checklist and a manual diff before deleting the old file.
• known.ts bloat. Keep details to one paragraph per element; long-form material belongs in the companion files.
• Skill path portability. ~ expansion in the generator; the skill lives outside the repo, so the drift guard cannot cover it — document that gen:skill-reference is the refresh command.
• Two references. docs/reference.md and the skill copy are both generated from known.ts; they must be regenerated together. Note this in docs/check-plan.md §9.