Skip to content

ByteTerrace/Puck / .claude/skills/puck-dsl

puck-dsl

Verified

Maps the .puck language: grammar, let/template/for, map/range builtins, puck compile/decompile/lint/format, PUCKnnn errors. Use for any .puck edit or JSON-to-.puck conversion. Shapes: sdf-authoring.

FileKindSize
SKILL.mdskill md20.0 KB
evals/p01-json-to-puck-cartridge/graders/arrays-without-colon.mdmarkdown70 B
evals/p01-json-to-puck-cartridge/graders/cursor-row.mdmarkdown114 B
evals/p01-json-to-puck-cartridge/graders/map-range-builtin.mdmarkdown169 B
evals/p01-json-to-puck-cartridge/graders/no-colon-before-a-bracket.mdmarkdown209 B
evals/p01-json-to-puck-cartridge/graders/scalar-colons-kept.mdmarkdown131 B
evals/p01-json-to-puck-cartridge/graders/skill-fired.mdmarkdown36 B
evals/p01-json-to-puck-cartridge/graders/variables-without-colon.mdmarkdown73 B
evals/p01-json-to-puck-cartridge/prompt.mdmarkdown354 B
evals/p02-puck040-and-puck037/graders/colon-refused-at-every-depth.mdmarkdown146 B
evals/p02-puck040-and-puck037/graders/core-parser-accepts-repeat.mdmarkdown144 B
evals/p02-puck040-and-puck037/graders/distinct-fixes.mdmarkdown106 B
evals/p02-puck040-and-puck037/graders/foreach-or-unrolled-effects.mdmarkdown323 B
evals/p02-puck040-and-puck037/graders/if-is-not-refused.mdmarkdown117 B
evals/p02-puck040-and-puck037/graders/puck037-nothing-to-lower-onto.mdmarkdown203 B
evals/p02-puck040-and-puck037/graders/puck040-drop-the-colon.mdmarkdown161 B
evals/p02-puck040-and-puck037/graders/skill-fired.mdmarkdown36 B
evals/p02-puck040-and-puck037/prompt.mdmarkdown474 B
evals/p03-180-zeroes/graders/compile-time-only.mdmarkdown120 B
evals/p03-180-zeroes/graders/compiled-json-keeps-the-values.mdmarkdown104 B
evals/p03-180-zeroes/graders/map-range-builtin.mdmarkdown133 B
evals/p03-180-zeroes/graders/skill-fired.mdmarkdown36 B
evals/p03-180-zeroes/prompt.mdmarkdown312 B
evals/p04-generate-locals-from-kicks/graders/for-in-the-rule-body.mdmarkdown103 B
evals/p04-generate-locals-from-kicks/graders/interpolated-local-name.mdmarkdown68 B
evals/p04-generate-locals-from-kicks/graders/not-five-rules.mdmarkdown141 B
evals/p04-generate-locals-from-kicks/graders/priced-like-hand-written.mdmarkdown120 B
evals/p04-generate-locals-from-kicks/graders/puck114.mdmarkdown64 B
evals/p04-generate-locals-from-kicks/graders/read-by-name.mdmarkdown96 B
evals/p04-generate-locals-from-kicks/graders/rule-when-or-if.mdmarkdown127 B
evals/p04-generate-locals-from-kicks/graders/skill-fired.mdmarkdown36 B
evals/p04-generate-locals-from-kicks/graders/unrolled-locals.mdmarkdown167 B
evals/p04-generate-locals-from-kicks/graders/when-in-for-refused.mdmarkdown118 B
evals/p04-generate-locals-from-kicks/prompt.mdmarkdown425 B
evals/p05-decompile-is-one-way/graders/compile-validate.mdmarkdown82 B
evals/p05-decompile-is-one-way/graders/edit-the-source.mdmarkdown181 B
evals/p05-decompile-is-one-way/graders/lint-strict.mdmarkdown77 B
evals/p05-decompile-is-one-way/graders/one-way.mdmarkdown194 B
evals/p05-decompile-is-one-way/graders/re-author-the-loops.mdmarkdown162 B
evals/p05-decompile-is-one-way/graders/skill-fired.mdmarkdown36 B
evals/p05-decompile-is-one-way/prompt.mdmarkdown486 B
evals/p06-world-rule-minus-equals/graders/long-form.mdmarkdown73 B
evals/p06-world-rule-minus-equals/graders/no-negated-add.mdmarkdown162 B
evals/p06-world-rule-minus-equals/graders/parser-accepts-it.mdmarkdown157 B
evals/p06-world-rule-minus-equals/graders/skill-fired.mdmarkdown36 B
evals/p06-world-rule-minus-equals/graders/two-effects.mdmarkdown190 B
evals/p06-world-rule-minus-equals/prompt.mdmarkdown216 B
evals/shade-runtime-slots/graders/slots-and-structure.mdmarkdown417 B
evals/shade-runtime-slots/prompt.mdmarkdown317 B
references/diagnostics.mdmarkdown8.6 KB
references/grammar.mdmarkdown18.7 KB

references/diagnostics.md

View on GitHub
# Diagnostics an author hits most

The full catalog is declared once, in
[`PuckDiagnosticCodes.cs`](../../../../src/Puck.Transpiler/Diagnostics/PuckDiagnosticCodes.cs),
and narrated with examples in
[`Puck.Transpiler/README.md`](../../../../src/Puck.Transpiler/README.md) and
[`Puck.World.Transpiler/README.md`](../../../../src/Puck.World.Transpiler/README.md).
Read those rather than a copy here for anything not listed below — a
restated catalog drifts the moment a code is added or reworded.

| Code | Severity | Fires on | Fix |
|---|---|---|---|
| PUCK040 | Error | A colon in front of a block or a list (`host: {`, `variables: [`). | Drop the colon: `host {`, `variables [`. |
| PUCK123 | Error | A section block holding only its rows (`kits { rows [ … ] }`). | Write the array of them: `kits [ … ]`; a section that also authors a policy member keeps its block. |
| PUCK121 | Error | An import spelling a file (`import "skies.puck"`, `import "theme.world.json"`). | Name what the file carries: `import "skies"`. A library's declarations or a document's composition follows from the named file, never the spelling. |
| PUCK002 | Error | Operand text an effect/`when`/`score` position handed to `Puck.State.ExpressionSpelling` failed to parse. | Fix the operand's own syntax — it is the rule language's expression grammar, not this document's. |
| PUCK024 | Error | A unit suffix on a field the vocabulary's dimension table doesn't cover. | Drop the suffix, or confirm the field name is the one the vocabulary actually declares. |
| PUCK025 | Error | A unit suffix the field's own dimension doesn't admit (e.g. `deg` on a field classified as time). | Use a unit from that field's dimension. |
| PUCK036 | Error | A statement inside `placements`/`prototypes` (or another section) that section's grammar has no case for. | Check the section's own grammar — an unrecognized statement is refused, never silently dropped. A statement that did not parse draws its parse fault alone, never PUCK036 as well. |
| PUCK037/038 | Error | Control flow or a call-form gate in a vocabulary whose rule shape cannot carry it. World rules admit `if` and compound assignment; `repeat`/`break` still fire PUCK037. | Iterate with `forEach`, unroll a fixed count with a compile-time `for`, or use a gate the vocabulary admits. |
| PUCK041 | Error | A compile-time call refused at the call: a collection builtin (`map`/`filter`/`reduce`/`range`/`length`/`concat`/...) or a scalar function called with arguments that can't be evaluated at compile time, or a name that is neither a compile-time function nor a document arm (`min`; the message names `minimum`). | Make every argument resolve to a compile-time value — no runtime state inside a builtin call; spell a function exactly as the vocabulary names it, with no abbreviation. |
| PUCK042 | Error | A lambda written where no builtin takes one. | A lambda is only ever an argument to one of the collection builtins. |
| PUCK043 | Error | An index (`a[i]`) that can't resolve at compile time — non-array/object target, fractional/unknown ordinal, or out of range. | Index a compile-time array/object with a whole-number or string key known at compile time. |
| PUCK044 | Error | A `for`'s sequence isn't an array known at compile time. | Bind the sequence to a `let`/literal array, or a builtin's compile-time output, first. |
| PUCK119 | Error | A row (`slot left: Element`, `row { enum: Element }`) or a record field (`field: Element`) names an enum the composed world's `state.enums` does not hold (drawn once by validating the composed world, so `lint` reports it; a basis's enums count). | Declare it with `enum Element { … }` here or in the basis; a cell kind (`: Int`) is never written there (PUCK107). |
| PUCK122 | Warning | An animated creation's pooled `group` joins, by a blend other than `Union`, shapes with different motion owners (drawn by validating the composed world, so `compile --validate`, `lint` and `creation stats` report it). The seam stretches as they move and bakes again once their relative pose settles. | Where the motion is meant, acknowledge it on the line before the row: `allow PUCK122 "why"`. Otherwise give both shapes one owner ([sdf-authoring](../../sdf-authoring/SKILL.md#making-it-move)). |
| PUCK131 | Warning | An animated creation's ungrouped shape declares a blend other than `Union` after another shape. The pooled bake gives each ungrouped shape a group of its own, so the blend draws as a hard union where a static placement draws it (`compile --validate`, `lint` and `creation stats` report it). | Give the shape and the shapes it blends into one `group`; PUCK122 then names any of them that move apart. |
| PUCK132 | Warning | A creation's driver authors a swing, a slide or a clip pose on a shape its mask (`parts`) does not cover, so the motion never plays (`compile --validate`, `lint` and `creation stats` report it). | Add a part covering the shape to the driver's `parts`, or drop the motion ([rig](../../sdf-authoring/references/rig.md#drivers)). |
| PUCK133 | Warning | A later effector writes a shape an earlier effector's tip hangs from, so the later one, solving last, can carry the earlier tip off its target (`compile --validate`, `lint` and `creation stats` report it). | Intended when the later contact should win; otherwise reorder the effectors or split their chains ([rig](../../sdf-authoring/references/rig.md#chains-and-effectors)). |
| PUCK125 | Error | A `let`, a `template` or a template parameter declared twice in one scope; the second declaration is refused and the first stands. `lint` adds no shadow or unused finding for it. | Rename or delete one. |
| PUCK124 | Error | An `allow` line naming a code no constant declares, giving no reason, or with no statement after it to cover. | Write `allow <code> "why"` directly above the row or `let` it covers. An error cannot be acknowledged. |
| PUCK120 | Error | A graph row's bound parameter is not a `parameter pass.member = value` statement inside its `graph` block: the statement stands elsewhere, binds one member twice, or the block writes a raw `parameters { }`. | Write one `parameter <pass>.<member> = <value>` line per bound member inside the `graph` block. |
| PUCK114 | Error | A `when`, `decision` or nested `rule` inside a `for` that stands in a rule body — a rule has one gate and one decision. | Write the condition in the rule's `when` or in an `if` inside the loop; stamp rules with a `for` outside any rule body. |
| PUCK047 | Error | Compilation work, source size, collection size, or nesting depth exceeded a ceiling. | Split the generated data or source into smaller pieces. |
| PUCK_LINT_005 | Information | A `state`/`comparandState`/`fromState` name, or a `State` token in a `compareValue`/`expression`/`score` operand, resolves to no declared state row. | Check spelling against the declared `state.*[].name` rows (including any basis/import). |
| PUCK034 | Warning | A shape's `parent` resolves to no sibling `name` in the same `shapes` array. | Fix the referenced name; this check is local and always runs, even inside a module. |
| PUCK049–066 | Error | A `table`/`slot`/`pile`/`grid` declaration refusal — outside `state.world`, a mixed array/block section, a duplicate name, an invalid default, a modifier the kind or shape doesn't admit, an inexact `advance` rate, an unknown or wrong-shaped `pile`/`grid` row reference, a `pile` capacity past its token domain, a `grid` kind other than `Int`/`Bool`, an invalid `grid` cell ordinal, `grid` `inverse` combined with authored cells, or a reused topology name. | See `Puck.World.Transpiler/README.md`'s [State declarations](../../../../src/Puck.World.Transpiler/README.md#state-declarations) table for the exact code-by-code list. |

PUCK034,
PUCK_LINT_010 (a vector-mix term whose weight share is below 1/64), and
PUCK_LINT_011 (division or remainder by a potentially zero divisor in an eager
ternary arm) are Warning
severity; every other `PUCK_LINT_*` check is Information, so `lint --strict`
(which promotes warnings to failures) does not fail on an Information-level
finding by itself. A `--strict`/`compile
--validate` failure with no PUCK_LINT line came from parsing, lowering, or
engine-schema validation instead — read the reported code, not the lint
family, to find it.

A document with no `schema`/`basis` of its own is a **module** — a fragment
some unknown root may import — and reference-resolution lint (PUCK_LINT_005
through 009) never reports an unresolved name against it standalone, since the
name may be one the eventual root supplies. Shape-parent resolution (PUCK034)
is the one check that ignores this distinction: it is scoped to sibling shapes
in the same array, which no basis or importer could change, so it always runs
and always reports.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall