Comprehensive Jai programming language reference and cheat sheet. Use when working with Jai code, tree-sitter-jai grammar development, or answering questions about Jai syntax and semantics. Covers declarations, types, control flow, directives, metaprogramming, and all language features. Trigger: user mentions 'Jai', 'Jai language', 'tree-sitter-jai', or asks about Jai syntax.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
40 files
Showing SKILL.md
SKILL.md
Source instructions ยท Read-only preview
name
jai-language
description
Comprehensive Jai programming language reference and cheat sheet. Use when working with Jai code, tree-sitter-jai grammar development, or answering questions about Jai syntax and semantics. Covers declarations, types, control flow, directives, metaprogramming, and all language features. Trigger: user mentions 'Jai', 'Jai language', 'tree-sitter-jai', or asks about Jai syntax.
Jai Language Reference
Complete reference for the Jai programming language by Jonathan Blow.
The Jai compiler distribution at ~/jai/jai/ contains the authoritative source:
how_to/ โ 84 .jai files across subdirectories covering all features
examples/ โ Real-world programs
modules/ โ Standard library
See references/cheatsheet.md for the full language cheat sheet.
See compendium/ for compilable code samples demonstrating every language feature
(33 entries: 32 single .jai files + the 30_module_parameters/ subdirectory entry).
See references/build-variables-recipe.md for the canonical
metaprogram recipe for custom compile-time build variables (#placeholder knobs module +
Message_Import-scoped add_build_string) โ including the beta 0.2.029 gated-#load bug the
naive per-file injection hits. Use this recipe whenever a metaprogram needs to feed constants
into target code.
Compendium verification requirement
Every compendium .jai file must compile without errors or warnings against the current Jai compiler. When updating the skill for a new Jai release:
Bump version headers in the cheatsheet and all compendium files.
Reconcile changelog changes with skill content (removed features, new syntax, etc.).
Compile every compendium file with ~/jai/jai/bin/jai-linux <file>.jai and confirm zero errors.
Where a file has runtime asserts, run it too โ compiling proves signatures, running
proves behavior (both matter: the beta 0.2.030 pass found Type_Info_Struct.alignment
only runs wrong, and a formatInt soft-deprecation only by reading the module).
Clean up build artifacts (rm -rf .build in the compendium directory; remove the built
binaries โ they are gitignored but should not linger).
Subdirectory entry:30_module_parameters/ is not a single file โ compile its driver with an
import dir:
~/jai/jai/bin/jai-linux compendium/30_module_parameters/driver.jai -import_dir compendium/30_module_parameters.
(Every other entry is a single [0-9]*.jai file compiled directly.)
Do not mark a version as verified until compilation is confirmed. The compendium is a "known good" corpus โ if it doesn't compile, the version stamp is a lie.
The cheatsheet's reliability rests on a robust correspondence between each section and a
compendium file that proves it compiles. Every cheatsheet section carries one banner:
<!-- compile-verified: beta X | compendium/NN.jai --> โ the section's constructs are
exercised by that compendium file, which compiles (and, where it asserts, runs) clean at
version X. This is the tier we trust for first-pass codegen.
<!-- inspection-only: beta X --> โ checked by reading the distribution at version X, not
compile-proven. The backlog: these await a compendium proof.
Linkage is bidirectional. A compile-verified banner names its proving compendium/NN.jai,
and that file's header carries a // Proves (cheatsheet): <section(s)> line. A section may be
promoted to compile-verifiedonly when a compendium file actually exercises its
constructs (not merely a topically-related file) โ a small compendium file cannot compile-verify
a large section it only partially covers; that is overclaiming, the same "stamp is a lie" trap.
Priority โ standard-module quick-refs first. Module signatures drift independently of
language syntax (beta 0.2.030 alone changed Thread/NewArray/File), so module quick-refs are the
highest-value compile-verified targets and must be proven by calling the real APIs.
Coverage status (beta 0.2.030, 2026-07-03): the per-section audit + closure is COMPLETE.
Every substantive cheatsheet section is now compile-verified (27 banners) against a compendium
entry; the audit that drove this lives in references/coverage-audit-2026-07-03.md and the closure
worklist in references/coverage-closure-plan-2026-07-03.md. The only inspection-only banner left
is Tree-Sitter Grammar Issues โ parser-development notes, not a claim about compiling Jai, so it
has no compendium proof by design.
Multi-artifact constructs โ proven by a DISTRIBUTION EXAMPLE (the third proof source). A few
constructs can't be demonstrated in our single-file corpus (they need a metaprogram / companion /
external link unit), but the Jai distribution ships multi-artifact examples that DO demonstrate them.
Citing such an example is a legitimate, lighter proof โ provided we CONFIRM it still compiles against
the current version (verified for beta 0.2.030, in scratch copies so the distribution is untouched):
#placeholder โ how_to/460_code_browsing_and_generation/ (build via first.jai) +
examples/add_build_string_into_specific_scope/ (build.jai); recipe in build-variables-recipe.md.
#load โ how_to/040_import_and_load/main.jai.
#elsewhere forms 2โ4 โ examples/dll/ (build.jai, builds a real .so).
Do NOT assume a shipped example compiles โ examples/module_info.jai compiles with a deprecation
warning at 0.2.030. So the cited examples are part of the release checklist too: re-compile each on
every version bump (scratch copies; compile-only is enough โ they need no run for signature proof).
Still unverified here (no self-contained example ships): #cpp_method /
#cpp_return_type_is_non_pod โ only used inside platform module bindings (modules/d3d11,
modules/Windows, modules/Check), which don't build standalone on this box. Genuinely open.
All of the above are noted at their cheatsheet banners.
When the audit found errors (this is the payoff โ the proofs are a bug-finder): the beta 0.2.030
closure corrected three cheatsheet mistakes (\/ is not a valid escape; `break/`continue/
`remove are not backtickable โ only defer/return/push_context/operators are; a ,,
allocator-override "demo" that didn't use ,,) and recorded two real 0.2.030 behaviors (compound
assignment through []/[]= calls only the SET overload; Type_Info_Struct.alignment is only
partially populated). Re-run the corpus each release and expect it to keep finding drift.
