Skmtc derives application code from an OpenAPI document treated as a\ndomain model. A stack of generators (small, opinionated,\ncloneable packages) is run by a deterministic engine that sweeps every\nsubject of the schema — each model (component schema, by refName)\nand each operation (path + method) — through each generator.\nOutputs are regenerated wholesale every run: never hand-edit generated\nfiles; customize the generator. Generators compose: a React-Query\ngenerator reuses the Zod generator's schemas through the engine's cache.
Generator source code is the customization surface: stock generators\nhardcode their export paths and peer imports on purpose, so the fastest\nreliable route to a correct generator is imitation of a published one —\nclone the structure, swap the target syntax. Pick the nearest exemplar:
\n| Need | \nClone | \n
|---|---|
| model → validator/schema value | \nload skmtc-model and copy its engine-tested skeleton (fill-in slots; gen-zod is its pattern source) | \n
| model → type declaration | \n@skmtc/gen-typescript | \n
| operation → client hook/SDK/form, consuming a model generator | \nload skmtc-operation (decomposition + peer-consumption rules; gen-tanstack-query-fetch-zod is its canonical instance) | \n
| many subjects → one shared file (accumulator) | \n@skmtc/gen-msw, @skmtc/gen-express | \n
| Kotlin | \n@skmtc/gen-kotlin-jackson (current lang-kotlin API; the older gen-kotlin-* were retired) | \n
Fetch source from JSR: https://jsr.io/@skmtc/<name>/meta.json → pick\nversion → fetch files (or deno doc jsr:@skmtc/<name>). Keep the\npackage convention exactly as cloned:
gen-x/ deno.json (name @scope/gen-*, EXACT-version @skmtc/* pins,\n lint plugin jsr:@skmtc/lint-plugin)\n mod.ts → re-exports + `export { entry as default }`\n src/mod.ts → the entry: toModelEntry / toOasOperationEntry\n src/base.ts → identity statics via the lang base factory\n src/enrichments.ts→ enrichment schema (emptyEnrichmentSchema opt-out)\n src/XProjection.ts→ constructor builds the value tree\n src/<router>.ts → schema-type → snippet dispatch\nWhat you adapt: the identity policy in base.ts (names, export paths,\nidentifier kind) and the router's per-type snippets (your target\nsyntax). What you keep: everything else — the shape is the point.
Three phases: parse → generate (your code runs here) → render\n(toString() runs once per file, only here). During generate the output\ndoes not exist; your generator builds object trees the engine can\nwalk, attribute, deduplicate, and settle imports from.
The trap: template strings full of target syntax\n(`export const ${name} = ...`) compile, render — and silently break\nimports (never settled into the header), reuse (text is invisible to the\ncache → duplicates), composition (peers can't reference text), and\nprovenance. Lint rules skmtc/no-template-imports and\nskmtc/no-adhoc-tostring catch the worst mechanically; keep them wired.
Litmus, applied at the keystroke: target-language punctuation inside\na string that will be STORED on an object → stop, build the object.\nStrings are legitimate as leaves: identifier names, export paths,\nmodule specifiers, literals, a cached peer name, and final syntax\nassembled inside a toString() body from already-structured fields.\nPrefer composing even render-time syntax inside toString() over helper\nfunctions that return strings — helpers drift.
toIdentifierName / toIdentifierType\n/ toExportPath are statics computed from (subject, enrichments, variant) WITHOUT constructing the projection. This is the invariant\neverything rests on: cheap cache probes, and peers knowing where your\nartifact will live. Never make a name depend on construction.(identifier.name, exportPath), and every producer creates its own\ndependencies. Generator order does not affect output; never propose\nordering, priorities, or a pre-generation pass. On a peer reference the Driver probes\nfindDefinition; hit → reuse (constructor never runs) + auto-stitched\nimport; miss → construct recursively. So: never hardcode a peer's name\nor path — insert and read the result, minding the two return shapes:\ninsertModel(Peer, refName) returns an Inserted handle (name via\n.toName(), definition via .definition), while\ninsertNormalizedModel(Peer, { schema, fallbackName }) returns the\ndefinition itself (name via .identifier.name). Never hand-write\npeer imports; never import a peer's naming helpers (ask\ncontext.toModelContentSettings if you need identity without\nmaterializing). Key collision under different generators throws\nRegistered definition mismatch.insertModel/insertOperation) and accumulator (many\nsubjects append into one definition — entry does\ncontext.findDefinition(...) ?? defineAndRegister(context, {...})\nthen mutates the container value; the sanctioned exception to \"no\nmethods beyond constructor and toString\"). defineAndRegister is a\nlang-package free function (import it from your lang package) —\nthere is no context.defineAndRegister; that API was deleted.toIdentifierName/toExportPath/toEnrichments)\nyourself, and never fabricate a refName — toRefName on a string you\nbuilt points at a schema that does not exist, and attribution,\nenrichment routing, and recursion tracking are all keyed by REAL\nrefNames; the fabrication survives only until something resolves it.\nIf the sanctioned call cannot express what you need, do NOT settle\nfor a degraded render — a widened type (Map<String, Any?> for a\nknown shape) is capitulation, not a solution. Treat the situation as\na solved problem you haven't found yet: research how other code\ngenerators handle this exact edge case — the stock lineup, retired\nin-house generators (git history is a design archive), and mature\nexternal tools (OpenAPI Generator, Fabrikt). The answer is almost\nalways to SYNTHESIZE a named declaration and reference it by name\n(findDefinition probe + your lang package's defineAndRegister).\nThe synthesized NAME derives from the schema's own stackTrail — a\npure function from position to name, computed at the point of need\n(components/schemas/Order/properties/metadata → OrderMetadata;\nan operation-rooted trail reuses toMethodVerb naming →\nCreateApiOrdersBody). Never thread a naming hint as a parameter:\nposition-derived names are deterministic, collision-free (distinct\npositions → distinct trails), and reach EVERY construction path —\nincluding values built through insertNormalizedModel's contract,\nwhich cannot pass a hint. Two rules: anchor on the document landmarks\n(components/paths), never absolute indices — the trail's head\ncarries per-run tracing frames (trace-*/span-*/parse); and\nthrow on an unrecognized or empty trail rather than invent a name\n(the engine isolates the throw to that subject). Worked example:\ntoSynthesizedName.ts in the kotlin-debug rig's gen-kotlin-jackson\n(verified end-to-end 2026-08-04, compiler-clean).\nOnly when the known solution needs machinery the engine genuinely\nlacks have you found an ENGINE GAP — name it in your summary and\nraise it; never silently ship the degraded form as if it were the\nanswer. Never re-create engine machinery inside a generator — a\nfaithful-looking counterfeit passes every automated check and breaks,\nfar from the cause, on the next engine change.'main' is always present. Thread the variant:\ntransform({ context, operation, variant }) →\npass variant through to insertOperation, and fold it into names\nwith withVariant. Dropping it collides every variant onto 'main'.subject/generator/stack) in enrichments.ts — that schema is\nthe whole contract the consumer's client.json can fill; the\nopt-out is\nexport const toEnrichmentSchema = () => emptyEnrichmentSchema — a\nFUNCTION returning the schema, required in both the entry config and\nthe base-factory config. Read via\nthis.settings.enrichments.subject?...; the run-constant scopes\n(client.json keys [id]._generator and ._stack, umbrella\nmembers generator and stack — no underscore in generator code)\nare read outside a projection with toGeneratorEnrichment /\ntoStackEnrichment. Declare every scope you read: a scope left\nv.undefined() rejects any value at its key (so _stack needs\nevery generator in the run to declare stack; check each\ngenerator's enrichments.ts — most stock ones declare subject only).\nA wrong-typed value fails that item only; keys the schema drops and\nrouting paths nothing read land on manifest.enrichmentWarnings.\nOptions come from the CALLING generator, on the insert:\nthis.insertModel(Peer, refName, { options: { suffix: 'Input' } }).\nA projection declares its options type on its base factory (the\nveneer's second type parameter: toTsModelProjectionBase<E, Options>);\nthe Driver hands them to toIdentifierName / toExportPath and the\nconstructor, and the instance stores them as this.options. Options\nare identity: fold them into toIdentifierName whenever the output\ndepends on them, or a second insertion with different options throws\nRegistered definition mismatch. The call surface follows the\ndeclaration — { options } is required when the peer declares\noptions and a type error when it does not; declare T | undefined\nto make it optional. Pass a fresh object per insertion. Module state\nis never a channel: it breaks determinism.refName casing (core's camelCase,\ncapitalize, decapitalize); operations from method + path via\ncore's toEndpointName (post→Create, put→Update). Never\noperationId — spec-author-controlled; no stock generator reads it.toString() is a prototype method\nreading precomputed fields (an arrow-function toString field breaks\nprovenance wrapping). Errors are isolated per subject — a throw kills\none artifact, not the run.Never guess a signature. Skmtc has almost no training-data presence;\nyour recalled API shapes are unreliable. Exact signatures for core\ncontracts (Oas* classes, Inserted, ContentSettings,\nTypeSystemArgs, entry configs) are one command away:\ndeno doc jsr:@skmtc/core@<pinned-version> <SymbolName> — read it\ninstead of guessing, and instead of casting around a type error. In\nparticular OasSchema is a union type, not a class hierarchy: every\nvariant implements .isRef() returning false, and OasRef is a\nsibling with .isRef() returning true.
Render does not run Prettier or Biome — no formatter runs inside the\nengine, so read the raw output as the generator produced it and format\nas a post-generation step.
\nGeneration is sub-second — run it after every meaningful change. Read in\norder: (1) manifest — expected definitions at expected paths? parse\nissues? per-item errors? (2) one golden artifact — import header\nfirst (missing import = a string swallowed a snippet), then the body;\n(3) deno lint; (4) if you consume a peer: their definition exists once\nand your file imports it. Never \"fix\" missing output by concatenating\nthe text into a template.
| Symptom | \nFix | \n
|---|---|
| Import missing / appears mid-file | \nDeclare via register, never in templates | \n
| Duplicate definitions of a shared model | \nReference peers via insertModel, not by name | \n
Registered definition mismatch | \nThread variant; or two generators claim one (name, path) | \n
Registered definition mismatch naming Cached options | \nThe peer's output depends on its options but its name ignores them — fold options into toIdentifierName | \n
| Peer output name wrong | \nRead .identifier.name off the insert result | \n
| Works once, breaks on recursion/refs | \nBuild tree in constructor; refs via the ref snippet/Driver | \n
| Enrichment ignored | \nUmbrella routing key mismatch — check warnings | \n
| Output edits vanish | \nYou edited generated files; customize the generator | \n
| Router misroutes custom values | \nschema.type === 'custom' is a real dispatch case — presence-test with 'readOnly' in schema-style guards, not type equality | \n
null slips through an optional guard | \n!== undefined lets null pass on Nullable generics — check both | \n
insertResult.identifier is a type error | \nYou have an Inserted handle (from insertModel) — use .toName()/.definition; only insertNormalizedModel returns the definition | \n
toRefName(`...${name}`) anywhere | \nFabricated ref — go through a peer's two doors, never its statics | \n
| Reading fields off a peer's value beyond the definition/name | \nCoupled to the peer's PRIVATE snippet shape — it will change silently | \n
The engine is language-blind; the import graph declares the language —\na generator imports its projection-base factories and snippet base from\nits language package, and the Drivers read the language off the\nprojection class. Everything concrete — base-factory names, snippet\nclasses, File/Import/Definition, identifier factories, emitted-language\nimport rules, sanitization — lives in that package and its skill.\nLoad skmtc-lang-typescript before writing code (the Kotlin layer has\nits own skill, not yet published). Lang skill wins on language\nspecifics; this skill wins on engine semantics. Two SHAPE skills carry the per-shape guidance — load the\none matching your subject: skmtc-model (fill-in skeleton, model\nedge cases: refs, recursion, visibility) or skmtc-operation\n(operation decomposition, peer-consumption rules). Shape-specific\nguidance lives there, not here.
Scope note: this skill covers OpenAPI input. GraphQL SDL input\nexists (toGqlOperationEntry, subject routing by\n[rootKind][fieldName]) and the engine rules here apply to it\nunchanged, but the GraphQL specifics — the entry, the enrichment\nrouting, the companion base factories — are not covered here.