update-typst-grammar-authoring

name	update-typst-grammar-authoring
description	Use when maintaining the portable typst-grammar-authoring skill from this repository's canonical Typst grammar source.
metadata	{"short-description":"Regenerate the portable Typst grammar skill"}

Update Typst Grammar Authoring

Use this skill when a maintainer needs to refresh the portable typst-grammar-authoring skill after changing the canonical grammar examples in src/tutorial/reference-grammar.typ.

Inputs And Outputs

• Canonical source: src/tutorial/reference-grammar.typ
• Portable skill: .codex/skills/typst-grammar-authoring/SKILL.md
• Traceability artifact: .codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json

Workflow

1. Review the source edits in src/tutorial/reference-grammar.typ and confirm they are ready to publish into the portable skill.

2. Regenerate the portable skill body and traceability artifact:

   python .codex/skills/update-typst-grammar-authoring/scripts/generate_grammar_catalog.py
   

3. Review the generated diff for the portable skill and the traceability JSON:

   git diff -- .codex/skills/typst-grammar-authoring/SKILL.md .codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json
   

4. Verify the portable skill stayed single-file:

   Get-ChildItem -Force .codex/skills/typst-grammar-authoring
   

5. Verify the portable skill's command examples stayed platform-neutral and did not reintroduce Windows absolute paths:

   rg -n "[A-Za-z]:\\\\|path\\\\to|target\\\\typst-grammar-authoring-check|\\.codex\\\\skills|src\\\\tutorial" .codex/skills/typst-grammar-authoring/SKILL.md
   

6. If the regenerated lookup looks correct, keep the portable skill focused on author guidance only. Any exact source mapping belongs in the updater-owned traceability JSON, not in the portable SKILL.md.

Guardrails

• Keep the distributed typst-grammar-authoring folder limited to SKILL.md.
• Treat .codex/skills/update-typst-grammar-authoring/references/grammar-catalog.json as the source-mapping artifact for maintainers.
• Keep maintenance-only commands, source-path references, and review steps in this updater skill rather than the portable one.
• If the generator output reveals a design issue in the portable skill, update the portable template first and rerun the generator before final review.