kami-narrative-grammar

Documents the markdown-to-TypeScript narrative authoring syntax for the kami-kakushi content pipeline.

1|Updated Jun 29, 2026
One-click install
npx skills add https://github.com/Raynos/kami-kakushi --skill kami-narrative-grammar-raynos
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kami-narrative-grammar
Source: https://github.com/Raynos/kami-kakushi/tree/main/.claude/skills/kami-narrative-grammar
Command: npx skills add https://github.com/Raynos/kami-kakushi --skill kami-narrative-grammar-raynos

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Story text in kami-kakushi is authored as markdown and compiled into generated TypeScript registries, and the compiler enforces a strict block grammar, line-id rules, and annotation vocabulary that are easy to violate. This Skill provides the syntax reference needed to edit narrative sources without breaking the gen-narrative gate. ## Core Features & Use Cases - Block grammar reference: Documents every heading form (## rung, ## scene-def, ## dialogue, ## ask, ## prose, ## requirements) plus effect annotations like memory:, flags:, bonus:, stance:, stat:, and perk:. - Compiler trap catalog: Explains failure modes such as the U+00B7 middle-dot separator, the <!--#slug--> line-id law, globally unique topic ids, and the prose-only takes gate. - Use Case: You edited rung-beats.md and the gen-narrative gate went RED with "motivates must be verbatim-equal" — load this Skill to find the exact rule, fix the source markdown, and regenerate the .gen.ts targets. ## Quick Start Ask the assistant to explain why the gen-narrative check fails on your edited narrative markdown file and how to fix the block syntax.

Frequently Asked Questions about kami-narrative-grammar

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a gen-narrative gate failure after editing story markdown?

Edit only the source .md files under src/core/content/narrative/, never the generated .gen.ts targets, then run pnpm run gen:narrative and commit source and regenerated targets together. The gate's RED message names the exact .md file to edit.

What is the <!--#slug--> line id marker used for in narrative markdown?

The <!--#slug--> marker assigns a permanent, save-facing id to greeting and answer lines so saved games address lines by name instead of index. Ids must never be renumbered or reused; rewording keeps the id while reordering lines is allowed.

Why does my narrative heading silently fail to parse?

The block-header grammar requires a U+00B7 middle dot with spaces as the separator, not a hyphen, and the regexes match it literally. A hyphenated heading is silently treated as non-heading prose.

When should I use the narrative-diverge skill instead of this grammar reference?

Use narrative-diverge for authoring any new fiction-voiced text or feedback-driven story changes, since ADR-139 requires shipping from three or more takes. This grammar skill is only the syntax reference used inside that process or for mechanical edits like typo fixes.

Can I add new requirement types to the requirements.md grammar?

No, the requirement spec grammar is closed: count, flag, state, and native forms only. Real logic escapes through the closed NATIVE_PREDICATES map in the requirements engine rather than by growing the grammar.