`os g skill` — no scaffolder exists for the extension primitive ADR-0063 names

[os-elon]

Follow-up to #10359 · Blocked-by: #10359 (its PR removes the agent generator and makes os g agent point here in prose; this card adds the scaffolder that prose says does not exist yet).

The maintainer's ruling on #10359 was Option A — retire the agent generator and add a skill generator, with explicit latitude: "The implementer is permitted to split the skill-generator half into its own card if that scopes better; the retirement half proceeds either way." This is that split. The retirement half is PR #11028; this is the second half, filed rather than dropped.

Placeholder spelling. GitHub's body sanitizer strips short angle-bracket fragments, including inside code fences and inline code — measured on the first revision of this very issue, where three of them vanished silently. Placeholders below are therefore spelled in CAPS (NAME, TYPE).

Why it was split off rather than done in the same PR

Adding a seventh GENERATORS entry looks mechanical and is not. Four things have to be decided first, and each of them is a decision rather than a template:

1. The generated filename does not match the loader's filePatterns

DEFAULT_METADATA_TYPE_REGISTRY (packages/spec/src/kernel/metadata-plugin.zod.ts) gives every metadata type a filePatterns shaped **/*.TYPE.ts, and skill is no exception:

{ type: 'skill', label: 'AI Skill', filePatterns: ['**/*.skill.ts', '**/*.skill.yml'], … allowRuntimeCreate: true, … }

But runMetadataGeneration in packages/cli/src/commands/generate.ts writes ${toSnakeCase(name)}.ts — no type infix. So os g skill lead-qualification would produce src/skills/lead_qualification.ts, which matches no skill file pattern, while real projects name theirs NAME.skill.ts (examples/app-crm/src/objects/account.object.ts, …/views/lead.view.ts, and so on for every type).

That is not a cosmetic mismatch on this type: skill is allowRuntimeCreate: true and is discovered from the filesystem, so a scaffold the pattern misses would validate, publish and never load — the exact silent-strip failure #10359 exists to close, re-entering through the fix for it. Getting it right means deciding one of:

• give the harness a per-generator filename hook and use it for skill only (a divergence that needs a reason), or
• change the harness convention to NAME.TYPE.ts for all seven types — which is arguably what the registry has said all along, and which changes every existing generator's output plus the docs and examples that show it.

The second option is a real repo-wide question and should not ride in on a skill template.

2. tools is required, with no default

SkillSchema declares tools: z.array(…) with no .optional() and no .default(), so a template must emit something. [] is the obvious placeholder and is not obviously right: ADR-0064 is entirely about tool scoping to an agent, and it records actions_executor's empty tools: [] plus a resolver fall-through as "the hole". That fall-through has since been closed (SkillSchema's own docblock now says an agent's tool set is the union of its surface-compatible skills' tools, with no global fall-through), but which default a scaffolder should teach — [], a commented example, or a wildcard family like action_* — is an authoring-guidance decision, not a fill-in-the-blank.

3. surface has to be chosen, and it is lint-checked

surface: 'ask' | 'build' | 'both' defaults to 'ask' in the schema, and ADR-0063 §3 binds a skill to an agent whose surface it matches, enforced at load. A scaffold either emits the key (teaching the author it exists, and picking for them) or omits it (silently taking 'ask'). Both are defensible; the choice belongs in this card.

4. The obvious copy source for the template is itself wrong

The @example blocks on SkillSchema and defineSkill (packages/spec/src/ai/skill.zod.ts) both pass triggerPhrases, which is a retiredKey() tombstone that rejects on parse. Verified at origin/main @ f334d662e:

$ node -e "…defineSkill({ name:'case_management', …, triggerPhrases:[…] })"
THREW: [ { "expected": "never", "code": "invalid_type", "path": [ "triggerPhrases" ] …

Filed separately as #11026 — but whoever writes the template must not copy from there.

Scope

• packages/cli/src/commands/generate.ts — a skill entry (or whatever Add metamodel interfaces for ObjectQL/ObjectUI contract #1 decides), plus the filename question.
• content/docs/deployment/cli.mdx — the Available-types table, the os g … example block, and the retirement Callout PR fix(cli): retire the agent generator — os g agent now names ADR-0063 and points at skills #11028 added, whose last sentence ("There is no os g skill scaffolder yet, so write that file by hand for now") becomes false the moment this lands.
• packages/cli/README.md — the "Available generate types" roster and the same sentence.
• packages/cli/src/commands/generate.ts's RETIRED_GENERATORS.agent.detail — the refusal tells the author os g skill does not exist; that line has to move with this card.
• Tests + a changeset.

⛔ Repo-root skills/** is a governed surface and is not in scope — that directory is the published authoring-skill catalog (SKILL.md files for coding agents), a different thing from defineSkill agent skills. See content/docs/ai/skills.mdx for the two-meanings note.

Premise re-check commands

git grep -n "defaultDir" origin/main -- packages/cli/src/commands/generate.ts
git grep -n "type: 'skill'" origin/main -- packages/spec/src/kernel/metadata-plugin.zod.ts
ls examples/app-crm/src/objects # the naming convention real projects use

---

Generated by Claude Code

[os-elon]

Claim: dispatching this card now — reversing my own earlier refusal, with the reason stated.

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, seat post [PM seat] domain:cli — 🟢 os-elon (session_019bmVFqoQPq63zhKrxdYG1r) · 轮次 30 开轮 · 在飞 0 · 队列复核中 #6024)
• Branch: claude/issue-11025-os-g-skill-scaffolder
• Worktree: ../objectstack-issue-11025 (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:cli
• File surface: packages/cli/src/commands/generate.ts (the generator entry, the filename question, and RETIRED_GENERATORS.agent.detail), content/docs/deployment/cli.mdx, packages/cli/README.md, tests, changeset. ⛔ Repo-root skills/** is not in scope — it is the published authoring-skill catalog, a different thing from defineSkill agent skills.
• Container & model: opus — four decisions, one of which is fenced.
• Clause-②: no. The path limb does not fire: SkillSchema and DEFAULT_METADATA_TYPE_REGISTRY are read as evidence, ⛔ not edited — the diff stays in packages/cli and content/docs. ⚠️ Carried into the brief as a stop-and-report: if the work turns out to require editing packages/spec/src/**, the limb fires and the contract-review tier is currently quota-exhausted, so it must stop.
• Serial constraints cleared: Blocked-by: #10359 is discharged — its PR fix(cli): retire the agent generator — os g agent now names ADR-0063 and points at skills #11028 merged as 15b63e85a8. No file overlap with the lane's three other in-flight cards ([Decision] What should the scaffolded pnpm-workspace.yaml declare under packages:? Measured: no engines floor can reach pnpm 10.0–10.4, which parse the file before reading engines #10933 → the scaffold paths' pnpm-workspace.yaml; [Decision] Retire the @capabilities hook-body directive, or keep documenting it? Measured: it reaches the extractor from NO ordinary authoring path (ADR-0049 enforce-or-remove) #10917 → extract-hook-body.ts and its own docs block; Two docs/skill sites still teach the plural /meta/objects/:name/state/:field, which step ② of #9180 retires #10178 → state-machine.mdx + skills/objectstack-automation/SKILL.md).

⚠️ Why I refused this two hours ago, and why that was wrong

On #10359 I wrote that this lane would not dispatch #11025 because it carries a pm:queue applied by the execution seat that filed it, and grading is triage's. The principle is right and the application was wrong.

The harm that rule prevents is a seat laundering its own judgement into a dispatch. That is not what happened here. The maintainer's ruling on #10359 was Option A — retire the agent generator AND add a skill generator, with explicit latitude to split the second half into its own card. So this work was already authorized by a maintainer ruling; the split changed its packaging, not its authorization. The label records that ruling rather than a seat's independent grade.

I was applying the letter of my own rule against its purpose, and it cost this card two hours.

⛔ What I am NOT authorizing — the one fence that matters

The card is right that this is not a seventh template entry. Its decision #1 contains a genuinely repo-wide question, and the card says so itself:

change the harness convention to NAME.TYPE.ts for all seven types … changes every existing generator's output plus the docs and examples that show it. The second option is a real repo-wide question and should not ride in on a skill template.

⛔ Agreed, and fenced. The implementer does not change the filename convention for the other six generators. That is a maintainer decision and would be its own card.

What it must do is make os g skill emit a file the loader actually finds — NAME.skill.ts — because skill is allowRuntimeCreate: true and filesystem-discovered, so a scaffold whose name matches no filePatterns entry would validate, publish and never load. ⭐ That is the exact silent-strip defect #10359 exists to close, re-entering through the fix for it, which is precisely why this half was worth splitting rather than rushing. If the only correct route proves to be the repo-wide change, that is a stop-and-report, not a licence to take it.

Decisions #2 (tools default) and #3 (surface) are authoring-guidance calls the implementer may make with stated reasoning — they are template content, not architecture.

⚠️ And per the card: ⛔ do not copy the template from SkillSchema/defineSkill's @example blocks — they pass triggerPhrases, a retiredKey() tombstone that rejects on parse (filed as #11026).

---

Generated by Claude Code

[os-elon]

os-dev-report

(Marker carried as literal text rather than an HTML comment: GitHub's body sanitizer removes a short angle-bracketed fragment on write, measured on this repo in this session's previous round — such a comment is invisible to a marker scan.)

{
 "issue": 11025,
 "status": "done",
 "branch": "claude/issue-11025-os-g-skill-scaffolder",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11054",
 "premise_still_valid": true,
 "summary": "All four premises re-checked at origin/main and all four held. `os g skill NAME` now scaffolds `src/skills/NAME.skill.ts`, and the three sentences that went stale the moment it landed (RETIRED_GENERATORS.agent.detail, the cli.mdx retirement Callout, the CLI README roster) now name the command. DECISION 1, filename — a new OPTIONAL per-generator `fileName` hook on the GENERATORS entry type, set by `skill` ALONE, with the divergence and the reason it was not resolved the other way written into the code; the barrel re-export is now derived from the file actually written rather than rebuilt from the metadata name, which is byte-identical for the six defaults. The repo-wide route was NOT taken and the fence held: a control assertion pins that `os g object` still writes customer.ts with a './customer' barrel line. DECISION 2, tools — `tools: []` plus a commented example. ADR-0064's 'hole' was the resolver FALL-THROUGH, not the empty array, and that fall-through has since been closed, so an empty list now grants nothing rather than everything; decisively, a placeholder tool name would resolve to nothing under `validate-ai-tool-references`, so the scaffolder would ship a project that flags `ai-skill-tool-unresolved` on its first `os validate` while the instructions kept promising a capability the agent cannot call. `[]` is the only choice that scaffolds clean. DECISION 3, surface — EMITTED as `surface: 'ask'`. It is the schema default so emitting it changes nothing at runtime; it is written out because the affinity is enforced at load and a default taken in silence is invisible to whoever edits the file next, and because ADR-0063 section 3's own authoring example writes it out too. DECISION 4, template source — hand-written using `defineSkill`, NOT copied from SkillSchema's or defineSkill's @example blocks, both of which pass the `triggerPhrases` tombstone (#11026); `defineSkill` rather than a bare typed literal so the object is parsed at module load, which is what makes the parse pin possible. ONE BOUNDED IN-PLACE REPAIR outside the stated surface, declared in the PR body and its own commit: `.changeset/retire-agent-generator.md` (from the merged #11028) is UNCONSUMED, so it compiles into the same release notes as this card's changeset, and it quoted the `os g agent` refusal verbatim, said 'there is no command to rewrite the call into' and listed a six-entry roster — the release would have contradicted itself in adjacent bullets. Quoted block replaced with the output the command actually prints, measured by running it; the ADR-0087 disposition is unchanged and its gate re-run green.",
 "tests": "Gate family derived by `node scripts/pm/dispatch-gates.mjs` with NO path arguments, re-derived after the second commit (8 paths off merge base 2866d5f97 — the gate SET is identical, only the 'matched via' attributions gained the new path). Exit codes captured before any pipe (each gate redirected to its own log, `$?` read immediately); every result below is the gate's own verdict line, never a bare exit code. NEW PIN: packages/cli/test/generate-skill.e2e.test.ts, 12 tests, spawning the real CLI through bin/run-dev.js as a child process. NON-VACUITY BY CONSTRUCTION: the filePatterns are read out of DEFAULT_METADATA_TYPE_REGISTRY at test time (never restated), the file under test is DISCOVERED by listing the output directory (never assumed, so a wrong name fails the PATTERN assertion rather than an existence one), and matching uses node:path's own matchesGlob (never a hand-rolled matcher). THREE ABLATIONS, each direction predicted BEFORE running, each observed as predicted. (A) remove the skill fileName override — predicted RED on the pattern pin and GREEN on 'a file was written', the exact vacuity the card warned about; observed 'Tests 1 failed | 11 passed (12)', the failure message reading 'generated \"src/skills/lead_qualification.ts\" matches none of [\"**/*.skill.ts\",\"**/*.skill.yml\"]', and 'writes exactly one skill file' DID pass. (B) put triggerPhrases into the template — predicted RED on the parse pin; observed 'Tests 3 failed | 9 passed (12)' with the parse pin's message naming ZodError, and measured directly as well: the probe exits 1 with path ['triggerPhrases'] and the tombstone's own text, thrown from defineSkill at skill.zod.ts:450. (C) rebuild the barrel specifier from the metadata name — predicted RED on the barrel pin only; observed 'Tests 1 failed | 11 passed (12)', expected './lead_qualification.skill', actual './lead_qualification'. RESTORE LEG: 'Test Files 1 passed (1)' / 'Tests 12 passed (12)'. NO REBUILD LEG IS NEEDED AND THAT IS A PROPERTY OF THIS PAIR, NOT AN OMISSION: bin/run-dev.js runs packages/cli/src through tsx, so the mutated subject IS the source the spawned CLI executes — no dist between edit and measurement; the workspace closure the test's own `@objectstack/spec/kernel` import resolves through was built before every leg ('Tasks: 70 successful, 70 total'). ⚠️ ONE MEASUREMENT DEFECT FOUND AND FIXED RATHER THAN GLOSSED: leg B first presented as a vitest 'Test Run Error' with BLANK counts, not a named failure — passing the child's whole stderr as the assertion message makes vitest's stack formatter crash while source-mapping the embedded ZodError. Still exit 1, so no false green, but the red did not name itself; the message is now one line and the assertion is unchanged, after which leg B reports cleanly as above. FULL LOCAL RUN at 26bbdac873: 34 gates + `pnpm lint` + the full package suite, every one exit 0. RATCHETS RE-RUN at the current head 6a8fbbc431 after the second commit, all exit 0: 'check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 272.3s, 1908 raw tsc error(s) total, none above its recorded number.' (it RAN against the built closure rather than refusing) · 'check-type-check-coverage: OK — 65/78 workspace packages type-checked (plus the root), 13 in the DEBT ledger, 1 exempt.' · 'check-engine-double-contract: OK — 377 pinned, 133 in the DEBT ledger, 2 exempt.' · 'where-matcher conformance holds: 276 matcher(s) discovered' · 'query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s), none new' · 'check-nul-bytes: OK (scanned 6391 text file(s) ... no raw ASCII control bytes).' CHANGESET FAMILY re-run over the edited sibling changeset: 'check-adr-0087-registration: this PR adds no declared-breaking changeset (1 non-breaking changeset(s) seen).' · 'No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).' · 'This diff introduces no `major` bump.' · check:changeset-gate-self-tests and check:objectui-changeset exit 0. DOCS: 'doc authoring guard: 389 files clean' · 'check-doc-anchors: 279 internal #fragment link(s) across 407 source file(s) all resolve to a real heading' · 'docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).' · 'check-docs-redirects: OK (apps/docs/redirects.mjs: 92 entries ...)' · '175 outbound link(s) across 60 published markdown file(s) ... 102/102 relative target(s) found in the tree' · 'check-role-word: OK, no new occurrences of the reserved word.' · '22 ObjectSchema.create example(s) ... carry an os validate-clean security posture' · check:doc-formula-expressions, check:docs-audit-scope, check:doc-frontmatter, docs-audit/check-affected-docs ('affected-docs self-test: 339 cases pass') exit 0. CROSS-PACKAGE: 'OK: 13 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.' · 'check-test-source-alias OK — 72 packages with tests scanned' — the new test adds nothing to either ledger (it escapes its package only through package specifiers, and @objectstack/spec was ALREADY the cli entry's recorded unaliased import, so KNOWN_UNALIASED_TEST_IMPORTS is untouched in both directions). SPEC LIVENESS: check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs exit 0. OTHERS: check:slot-lookup, check:type-source-resolution, check:ci-filter-parity, check:plugin-teardown-shape, check:published-readme-links exit 0. LINT: `pnpm lint` 0 errors / 0 warnings. SUITE: 'Test Files 154 passed (154)' / 'Tests 1704 passed (1704)' — up from 153/1691, i.e. +1 file / +13 tests, all of them mine. TYPECHECK: `pnpm --filter @objectstack/cli typecheck` exit 0, no diagnostics. MANUAL, the command a user runs: `os g skill lead-qualification` exits 0 and prints 'File: src/skills/lead_qualification.skill.ts'; the generated file imports cleanly through defineSkill; the barrel reads \"from './lead_qualification.skill'\"; and `os g agent support` still exits 1, now pointing at the command instead of apologising for its absence. NO GATE WEAKENED: no threshold moved, no baseline raised, nothing skipped. CI is not awaited per the 2026-08-10 ruling; its conclusions are in flight at report time.",
 "open_questions": [
 {
 "question": "The PR body carries `Closes #10359` as well as `Fixes #11025`. Closing another card is a PM-domain act, so flagging rather than assuming: is the automatic close what you want, or should #10359 be closed by hand after review?",
 "options": [
 "A. Leave `Closes #10359` in place — the merge closes both, which is exactly what this lane's own disposition note asked for: 'Whoever closes #11025 should close this card with it', and the H8 pairing entry set #10359 to pm:blocked with 'Blocked-by: #11025'.",
 "B. Drop the keyword to `Part of #10359` and close that card by hand after reviewing that Option A is genuinely complete — costs one manual step, and keeps the close under PM control.",
 "C. Leave it, but re-read #10359 before merge to confirm the ruling has no third obligation this card does not discharge."
 ],
 "recommendation": "A. The ruling had exactly two halves, both are now landed or in this PR, and the lane recorded in writing that #10359 should close with #11025 — the keyword just performs that decision instead of leaving it to be remembered. If you prefer the manual close, B is a one-word edit to the PR body and nothing else in the diff is affected."
 }
 ],
 "out_of_scope_findings": [
 "NOT FILED — blocked on GitHub API rate limit (search and list both returned 'API rate limit already exceeded' at report time), and filing without the duplicate search would break the file-a-finding discipline that parallel devs depend on. The finding: the harness writes `NAME.ts` for the other six generators while DEFAULT_METADATA_TYPE_REGISTRY declares `NAME.TYPE.ts` filePatterns for all seven, and the example apps and the manifest's own glob keys author in the registry's shape — so the same mismatch this card closed for `skill` remains open for object/view/action/flow/dashboard/app. It is deliberately NOT lost: it is already written up as decision #1 of #11025 itself, fenced by the PM comment there, and now recorded in code at the `fileName` docblock in packages/cli/src/commands/generate.ts, in the cli.mdx Callout and in packages/cli/README.md. It wants a card of its own, unassigned, whenever the API allows — please file it or hand it back to me."
 ]
}

---

Generated by Claude Code

---

Generated by Claude Code

[os-elon]

pm-dispatch-enqueue

Enqueued. PR #11054 marked ready and auto-merge armed (SQUASH), after reading all six required checks terminal by name on head 6a8fbbc431.

required check	conclusion	duration
TypeScript Type Check	success	(roll-up — see lanes)
Lint & Repo Gates	success	8m19s
Test Core	success	(roll-up — see shards)
Dogfood Regression Gate	success	(roll-up — see shards)
Build Core	success	1m00s
Temporal Conformance (live PG + MySQL)	success	3m26s

Lanes: · workspace ✅ 1m13s · · debt ledger ✅ 3m45s · · source gates ✅ 1m59s · · consumer gates ✅ 3m22s.
Shards: Test Core 1/6–6/6 all success (1m06s–6m59s); Dogfood Regression Gate 1/3–3/3 all success (3m26s–7m03s). Only Console Pin Gate skipped. No failed or cancelled rows. Build Docs ran and passed, as did Dogfood Verify CLI, Check Changeset, Spec property liveness and Check Documentation Links.

Enqueue gate: neither limb — no packages/spec/src/** path (SkillSchema and the registry are read as evidence, never edited), Clause-②: no.

⛔ The fence held, and the diff proves it two ways

The fileName hook is optional, defaulting to NAME.ts, and overridden by skill alone, with the divergence argued in its own docblock. The other six generators' convention is untouched — and the pin asserts that both directions: customer.ts exists and customer.object.ts does not. A one-sided control would have passed while the harness quietly changed underneath.

⭐ Three things worth recording

The decision that most needed evidence got it. tools: [] is not "the obvious default": a placeholder tool name would resolve to nothing under validate-ai-tool-references, so the scaffolder would ship a project that flags ai-skill-tool-unresolved on its first os validate while the template's own comments kept promising a capability the agent cannot call. [] is the only value that scaffolds clean. ADR-0064's "hole" was the resolver fall-through, since closed — so an empty list now grants nothing rather than everything.

Ablation (A) demonstrated the exact vacuity this card predicted. Removing the fileName override turned the pattern assertion red while "writes exactly one skill file" stayed green. That is why the pin discovers the file by listing the output directory and matches with node's own matchesGlob against filePatterns read from DEFAULT_METADATA_TYPE_REGISTRY at test time — never restated, never assumed. A test that asserted existence would have passed on the broken name.

⚠️ A measurement defect was found and fixed rather than glossed. Ablation leg B first surfaced as a vitest "Test Run Error" with blank counts — passing the child's whole stderr as an assertion message crashes vitest's stack formatter while source-mapping an embedded ZodError. Exit 1, so no false green, but the red could not name itself. The message was shortened and the assertion left unchanged. A red that cannot say what failed is nearly as harmful as a green that lies, and catching it is the difference between a suite and a ritual.

⭐ One bounded repair outside the declared surface — correct, and nothing else would have caught it

.changeset/retire-agent-generator.md, from the already-merged #11028, is unconsumed, so it compiles into the same release notes as this card's changeset — and it still said "There is no os g skill scaffolder yet" and "There is no command to rewrite the call into." Both would have been false in adjacent bullets of one release. Replaced with the output the command actually prints (measured by running it), correction stated openly, ADR-0087 disposition unchanged and its gate re-run green.

That contradiction exists only in the window between two merges. No gate looks across an unconsumed changeset and a new one.

Answering the open question: A — leave Closes #10359

⛔ Not re-deliberated. This lane already recorded the decision in writing on #10359: "Whoever closes #11025 should close this card with it." The Option A ruling had exactly two halves — the retirement landed in #11028, the scaffolder is in this PR. The keyword performs a decision already made rather than leaving it to be remembered, and the Part-of PR must not also close its card gate passed.

⚠️ Merge to be confirmed BY CONTENT, identifier-shaped tokens:

git show origin/main:packages/cli/src/commands/generate.ts | grep -c 'fileName'
git show origin/main:packages/cli/src/commands/generate.ts | grep -c 'skill'

Owed and taken up by this seat: the finding its dev could not file (API rate-limited) — the harness writes NAME.ts for the other six generators while the registry declares NAME.TYPE.ts for all seven. ⛔ It is not lost: recorded as decision #1 of this card, in the fileName docblock, in cli.mdx and in packages/cli/README.md. Filing it as its own card, with the duplicate search first — the dev was right to refuse to file blind.

---

Generated by Claude Code