# Update Typst Grammar Authoring

> Use when maintaining the portable typst-grammar-authoring skill from this repository's canonical Typst grammar source.

- Skill: `tomevault-io/update-typst-grammar-authoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/update-typst-grammar-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/update-typst-grammar-authoring/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/update-typst-grammar-authoring

---


# 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:

   ```sh
   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:

   ```sh
   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:

   ```powershell
   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:

   ```sh
   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.

---
> Source: [typst-doc-cn/tutorial](https://github.com/typst-doc-cn/tutorial) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-25 -->