skills(ai): optimization flight — the closed agent surface cut to its retirement rows, the flagship defineSkill example made to resolve, open-edition MCP wiring and the tool registry taught (net −1,315 tokens)

[os-litant]

Part of #14305

Skills catalog optimization program #14292 (maintainer mandate 2026-09-02). Not a closing
reference: AI-H-01 (the evals/README.md stub) is deferred to #14296 item 2, so the card
stays open.

Transliteration key — the GitHub body sanitizer eats angle-bracket-shaped fragments, so
two are spelled without them below: action_NAME = the action_ prefix plus an
angle-bracketed name placeholder (rung 3 of the tool-resolution ladder), and
os-check-marker = the HTML-comment fence marker check-skill-examples.ts keys on.

Per-file token delta

File	before	after	Δ	ceiling	headroom after
skills/objectstack-ai/SKILL.md	6,791	5,476	−1,315 (−19.4%)	6,806	1,330 (was 15)
skills/README.md	—	—	generator output	—	not ratcheted
content/docs/ai/skills-reference.mdx	—	—	generator output	—	not ratcheted
scripts/role-word-baseline.json	—	—	one-line ratchet-DOWN	—	—

Lines 592 → 419. evals/README.md (315/315) and the generated references/_index.md
untouched; no ceiling raised; no new file; scripts/check-skills-token-ratchet.mjs untouched.

落点 | before | after

id	落点 (before → after)	before	after
AI-A-01	frontmatter description :3-10	promised "AI skills, tools, knowledge sources, conversations, model registry entries, and MCP integrations" — three surfaces the body never taught, all three with zero consumers outside packages/spec	"skills, tools, knowledge sources, and the open-edition MCP server surface". MCP earns its place back because the body now teaches it (below). Regeneration of the two generated catalog files is the only reason they are in this diff
AI-A-02	:475-491 → Model Configuration	two taste tables — "GPT-4o / Claude Sonnet 4 for complex reasoning", "0.7–1.0 Creative writing" — and the enforced bound absent	one contract table. temperature is min(0).max(2), default 0.7; outside 0–2 is a parse error (packages/spec/src/ai/agent.zod.ts:38)
AI-B-01	:40-50 "When to Use This Skill"	a 5-bullet restatement of the frontmatter the agent has already read	deleted
AI-B-02	:145-215 agent Required / Optional / 34-line defineAgent example	792 tokens opening with its own "third parties do not author agents"	two retirement rows (agent.tools, agent.knowledge) + a pointer to references/_index.md, inside the new bottom reference section
AI-B-03	section order	the first customer-authorable section began at line 218 (33% preamble)	## Skill Configuration is now the first section after the boundary anchor and the tier diagram; the closed agent surface is a reference section at the bottom. Free — reorder only
AI-C-01	:28-36, 83-86, 89-90, 126-131, 330-335, 339-342, 360, 364-365	"the runtime is cloud/EE; open is MCP-only" restated 8× (715 tokens)	one anchor blockquote that defines a bare cloud marker, then that marker on the affected headings
AI-C-02	:138-141 ops callout	AI_DAILY_USER_MESSAGES, ai_usage_daily, GET /api/v1/ai/status — cloud ops, and ai_usage_daily has no object in the open repo	deleted (ops belongs to objectstack-platform)
AI-D-01	:63-73 "Why Three Tiers?"	a 3-row analogy table + a best-practice blockquote the diagram already carries	deleted; the ASCII diagram survives
AI-D-02	:24-26	"aligned with Salesforce Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns"	deleted
AI-D-03	:495-521 "Structured Output"	217 tokens on an agent-only field the same file forbids third parties and calls "declared only"	deleted. Its unmarked fenced fragment (a bare structuredOutput literal, TS1109 in statement position) goes with it
AI-D-04	:461-473 "Supported Providers"	a 4-row vendor model catalogue ("GPT-4o, o1, o3-mini"; "Ollama, vLLM, llama.cpp")	deleted; the two provider enums survive as a row
AI-D-05	:442-456 "Knowledge Source Best Practices"	5 numbered items restating the property table 30 lines above	merged into a Hygiene column on the source-kinds table
AI-D-06	:526-529, 541-544 pitfalls 1/2/4/5	generic prompt-engineering advice the frontmatter itself disclaims	1/2/4 deleted; 5 (no phrase matching) folded into the trigger-conditions construct
AI-D-07	:362-381 HITL	255 tokens of plugin snippet + 4-step flow narration + 4 IAIService method names, every symbol cloud-closed	one paragraph: what enableActionApproval: true holds, where it is triaged, and that the skip rule above is what decides whether your action is held
AI-E-01	:251-275 flagship defineSkill example	tools: ['query_support_case','create_support_case','update_support_case','escalate_case'] — all four unresolvable	tools: ['query_records', 'get_record', 'action_escalate_case'] with an inline comment naming the rungs. Measured below
AI-F-01	package-wide absence	zero hits for MCPServerRuntime / MCPServerPlugin / list_actions / run_action / /api/v1/mcp across all 11 published packages	a new ## MCP — the open-edition AI path section. Paid by AI-D-03
AI-F-02	:386-391 RAG wiring	"registered at runtime via IKnowledgeService.registerSource()" and the package that provides it named nowhere	KnowledgeServicePlugin({ sources }) from @objectstack/service-knowledge, plus the two adapter packages the adapter ids need. Paid by AI-D-05
AI-F-03	:277-286 trigger table	5 operators, no value shape — { operator: 'in', value: 'admin' } is a parse error the package never warned about	a third column. Paid by AI-D-01 + AI-B-01
AI-F-04	:289-335, :559 defineTool	a full section plus a blueprint row presenting a zero-usage, zero-reader surface as a standard layer	a "not the default path" note carrying the ADR-0109 quote; the blueprint row is gone
AI-G-01	:71-73 vs :168	"Direct tool assignment to agents is supported but considered legacy" — contradicted 145 lines later by the same file	deleted with AI-D-01. See falsehood 1
AI-G-02	:579-580	"any CEL predicate (e.g. a tool's availability condition)"	"in this domain that is a model-registry promptTemplate.system / .user; ToolSchema carries no expression field of any kind". See falsehood 2
AI-G-03	:297 outputSchema	presented as a peer of objectName, silently reading as enforced	flagged experimental — keys folded into the tool description, outputs not validated — matching how the file already flags guardrails / memory / structuredOutput
AI-E-02	fence-marker audit	6 ts fences, 4 marked	3 fences, 2 marked. The two marked blocks that went away are the ones whose sections went away (defineAgent under AI-B-02, defineTool under AI-F-04). The corpus is 265 → 263 blocks and stays green

The three funded additions — every claim read at source

1. Open-edition MCP wiring. MCPServerPlugin / MCPServerRuntime are exported from
packages/mcp/src/index.ts:13-16. The HTTP surface is default-on, served per-request by
the runtime dispatcher at POST /api/v1/mcp (packages/mcp/src/plugin.ts:110-118;
OS_MCP_SERVER_ENABLED=false opts out), and stdio is a separate opt-in on its own switch —
see Review round 1 below, which corrected which switch that is.

Tool names: the card's four are confirmed, and the list was incomplete. Read from the
registerTool call sites in packages/mcp/src/mcp-http-tools.ts: list_objects (:324),
describe_object (:380), validate_expression (:406), query_records (:464),
aggregate_records (:506, conditional on the bridge implementing aggregate), get_record
(:580), create_record (:605), update_record (:626), delete_record (:648), and from
registerActionTools list_actions (:708) and run_action (:732). So:

• ✅ list_actions, run_action, query_records, describe_object — all four exist, and
  examples/app-todo/test/mcp-actions.e2e.ts:110-113 asserts the first three on a real
  JSON-RPC tools/list.
• ⚠️ corrected: the card's four-name list understated the surface. The section now
  carries all eleven, grouped, with the scope gate on each family.
• ⚠️ corrected: the MCP aggregate tool is aggregate_records, not aggregate_data.
  aggregate_data is a different name in a different registry — a service-ai platform
  tool (platform-tool-names.ts:44). Both spellings now appear in the file, each in its own
  registry, which is exactly the confusion the section prevents.

The MCP wiring fence is deliberately unmarked (PM assumption 4, confirmed): the
os-check-marker gate compiles blocks against three surfaces —
skills + docs (@objectstack/spec), spec source TSDoc, client SDK (@objectstack/client-react, @objectstack/client) — and @objectstack/mcp is in none of them, so the block could not be
marked without the gate refusing to resolve the import. Both remaining marked blocks compile
against @objectstack/spec declarations only.

2. The skill.tools[] ladder and the platform registry. The ladder is
stack.tools[].name ∪ PLATFORM_PROVIDED_TOOL_NAMES ∪ action_NAME
(packages/lint/src/validate-ai-tool-references.ts:148-171, collectToolUniverse).
Counted, as asked: exactly 30 names in
packages/spec/src/system/constants/platform-tool-names.ts — 6 under service-ai (:43-50)
and 24 under service-ai-studio (:56-81); the const spans :38-82, so the card's :38-80
was one line short of the closing brace. The 6 are enumerated in full; the 24 are given as a
representative sample plus the file pointer, deliberately, to keep the addition inside its
budget.

3. The trigger-condition operator ↔ value-shape column. SKILL_TRIGGER_LIST_VALUE_OPERATORS
= ['in','not_in'] (packages/spec/src/ai/skill.zod.ts:37),
SKILL_TRIGGER_SCALAR_VALUE_OPERATORS = ['eq','neq'] (:51), enforced by
superRefine(checkSkillTriggerConditionValueShape) (:139-191) on
SkillTriggerConditionSchema (:193-202). contains is deliberately in neither list and
accepts both. Driven against the real schema below.

The two falsehoods

1 — agent.tools is a tombstone, not "legacy". The file said "Direct tool assignment to
agents is supported but considered legacy" at :71-73 and "REMOVED in protocol 17 … A
parse error now" at :168 — 145 lines apart. Implementation sides with :168:
tools: retiredKey('...agent.tools was removed in @objectstack/spec 17 — use skills...')
(packages/spec/src/ai/agent.zod.ts:234). Rewritten: both retired keys now sit in one
"tombstones, not legacy options — authoring either is a parse error carrying its migration"
table, with agent.knowledge (:251) beside it. The "supported" sentence is gone.

2 — no CEL carrier on ToolSchema. The verify section cited "any CEL predicate (e.g. a
tool's availability condition)". ToolSchema declares exactly name, label,
description, parameters, outputSchema, objectName
(packages/spec/src/ai/tool.zod.ts:132-168) — no condition or expression field of any kind.
Rewritten to name the real AI-domain carrier, the model-registry promptTemplate.system /
.user, which is what skills/objectstack-formula/SKILL.md:473 already states correctly.

Follow-up for skills/README.md (not fixed here — the card forbids hand edits to that
file's prose, and this flight touches it only as generator output): skills/README.md:104-105
routes "AI tool params" to objectstack-formula on the same false premise as falsehood 2.
There are no AI tool params carrying CEL. The routing row should either name the
model-registry promptTemplate carriers or be dropped. Owner: whoever holds the catalog
routing table.

premise_false

None. Every finding's cited span was present and said what the audit reported. git diff --stat a59f78d..d16df741 -- skills/objectstack-ai/ is empty, so PM assumption 1 held and no
span had to be relocated by content.

The −2,108 gap, itemised (not smoothed)

The card asks for ≈ −2,300 net in-file. That figure is the audit's package net, and it
includes the deferred evals/README.md −195. The audit's own in-file arithmetic is
−2,108 (−2,420 deletions +312 additions). Delivered: −1,315. The 793-token gap
decomposes, measured on the final file:

	audit booked	actual in-file	gap
MCP section (AI-F-01)	+180	+410	+230
Tool-resolution ladder (funded addition 2)	+0 ("paid by AI-B-02")	+319	+319
Trigger-condition column (AI-F-03)	+30	+158 (55 → 213)	+128
Knowledge wiring (AI-F-02)	+90	+105	+15
outputSchema caveat (AI-G-03)	+12	~+12	0
additions total	+312	≈ +1,004	+692
deletions total	−2,420	≈ −2,314	+106

The dominant term is structural, not slippage: the audit books funded addition 2 at +0
by charging it to AI-B-02's −600, while also counting that −600 in the deletion total. A
319-token addition cannot be free and also be a 600-token deletion. The second term is the
MCP section, where the +180 budget did not cover the eleven real tool names plus the
default-on/stdio distinction; I judged the names worth the overrun — they are the whole
point of the addition, and the file still lands with 1,330 tokens of headroom against a
ceiling it previously had 15.

The 106 of under-delivered deletion is spread across sections where the audit's estimate ran
ahead of what could go without losing a decision (chiefly Model Configuration and the
Actions/Tool split); no section was left uncut.

Ruled A by contract review round 1 — accept the net cut; no second pass.

Out-of-scope cards filed

• [finding] skills/objectstack-ai tells authors metadata_assistant is "not vocabulary" while the platform's own Studio app pins defaultAgent: 'metadata_assistant' #14461 — metadata_assistant: the skill says the legacy alias is "not vocabulary"
  while packages/platform-objects/src/apps/studio.app.ts:50 pins
  defaultAgent: 'metadata_assistant' — the only app.defaultAgent usage in the repo. Three
  readings, graded rather than patched.
• [finding] The objectstack-ai generated reference index advertises 6 schemas the SKILL.md never teaches and omits the one it names — SKILL_MAP in build-skill-references.ts is unreconciled with the body #14462 — AI-B-04: the generated references/_index.md advertises 6 schemas the body
  never teaches, and SKILL_MAP (packages/spec/scripts/build-skill-references.ts:98-109)
  omits ai/solution-blueprint.zod.ts, the schema behind the solution_design skill the
  body names.
• [finding] MCPServerPlugin's own docblock still teaches the deprecated stdio trigger — plugin.ts:112-122 disagrees with plugin.ts:234-239 twelve lines below it #14473 — the stale MCPServerPlugin docblock that produced review round 1's FAIL (see
  below).

All unassigned, finding label, no pm-state, no priority. Dedupe was a targeted
search_issues per card (repo-scoped REST answers 403 for this seat), each returning a
non-empty result set, so the session's search is not in the silent-zero failure mode.

Gates — head 5dabfd2a

Family re-derived after regeneration, as the card requires:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands → the
.mdx + skills/** change set produced 36 commands; adding scripts/role-word-baseline.json
(below) grew it to 42, and all 42 were re-run in full on this head after the round-1 patch
(the re-derived list came back byte-identical to the 42 already run). Exit codes captured
before any pipe, one log per command.

42 run · 41 green · 1 NOT MEASURED · 0 red.

• node scripts/check-skills-token-ratchet.mjs — ✓ 37 authored bundle file(s) within their ceilings; skills/objectstack-ai/SKILL.md is 5476 tokens (ceiling 6806; headroom 1330).
• pnpm --filter @objectstack/spec check:skill-examples — ✅ 263 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them. @objectstack/spec and the @objectstack/client-react closure were built first (this gate refuses a stale or missing dist rather than false-greening).
• pnpm check:skill-compatibility — ✓ 11 SKILL.md file(s) reconciled against 78 workspace packages.
• pnpm check:skill-identifier-liveness — OK — Leg 1: 480 citation(s) over 47 published file(s) … Leg 2: 8 registered exhaustive section(s), 0 ledgered gap(s).
• pnpm --filter @objectstack/spec check:skill-docs — ✓ skills/README.md, ✓ content/docs/ai/skills-reference.mdx, ✅ Skill docs in sync.
• pnpm check:role-word — check-role-word: OK, no new occurrences of the reserved word.
• pnpm check:skill-frame-sync, check:doc-authoring, check:doc-anchors, check:docs-single-h1, check:published-readme-links, check:corpus-claim-drift, and the rest of the 42 — green.
• node scripts/check-test-completeness.mjs — exit 3, NOT MEASURED. Its own text: "this gate grades a saved turbo run test log, and no log was named … running the family locally, record this gate as NOT MEASURED. ⛔ It is not a red." CI tees the log and passes the path.

PM assumption 3, measured before the first deletion: check-skill-identifier-liveness's
Leg 2 BINDINGS table registers 8 exhaustive sections across objectstack-api, objectstack-data
(×3), objectstack-platform and objectstack-ui (×3). None is in
skills/objectstack-ai/SKILL.md, so no heading in this file was bound and the reorder and
deletions were free of Leg 2. Leg 1 citations dropped 490 → 480 with the gate still green.

One extra file, mechanically forced. check:role-word went red at exit 1 with a
ratchet-DOWN: role-word count improved 5 → 1 — run --update and commit the baseline.
That gate's remedy for a downward ratchet is explicitly the author's own, so
node scripts/check-role-word.mjs --update was run; the diff is the single line
"skills/objectstack-ai/SKILL.md": 5 → 1 in scripts/role-word-baseline.json. No other
line changed, and no other file was touched to satisfy a gate. The round-1 patch did not
move that count again — check:role-word returned exit 0 with OK, no new occurrences, so
the baseline is unchanged on this head.

Staleness, checked rather than assumed. dispatch-gates warned that origin/main had
moved past my base. git diff d16df741..origin/main -- .github/workflows/ package.json shows
only release.yml, and it changes no skills/**, content/** or docs/** path filter — so
the derived family is unaffected. The branch is deliberately still based on the dispatched
d16df741.

Verification of the rewritten example and the new claims

AI-E-01 — the real rule, both directions. validateAiToolReferences (the exported
ai-skill-tool-unresolved implementation) was driven over the shipped example's tool list
and the rewritten one, against a stack carrying one AI-exposed escalate_case Action and
no stack.tools records (the ADR-0109 default path):

OLD (shipped example): 4 finding(s)
  ai-skill-tool-unresolved  skills[0].tools[0]  "query_support_case"
  ai-skill-tool-unresolved  skills[0].tools[1]  "create_support_case"
  ai-skill-tool-unresolved  skills[0].tools[2]  "update_support_case"
  ai-skill-tool-unresolved  skills[0].tools[3]  "escalate_case"   ← Did you mean "action_escalate_case"?

NEW (rewritten example): 0 finding(s)

Predicted direction before running: old red, new clean. Observed: exactly that, and the rule
volunteered the near-miss hint on escalate_case — the same one-word slip the old example
taught. The driver was written into the worktree, run, and deleted in the same step; the tree
is clean (git status empty).

Funded addition 3 and AI-A-02 — driven against the real schemas, not transcribed:

--- trigger-condition value shape ---
PARSES   in    + array  ['admin']
REFUSES  in    + string 'admin'    -> Operator "in" on field "userRole" requires an ARRAY of values…
PARSES   in    + empty array []
PARSES   eq    + string 'x'
REFUSES  eq    + array ['x']       -> Operator "eq" … requires a single STRING value…
PARSES   contains + string
PARSES   contains + array
--- model.temperature bounds ---
PARSES   0 · 0.7 · 2
REFUSES  2.1   -> Too big: expected number to be lte 2
REFUSES  -0.1  -> Too small: expected number to be gte 0

(the two bound messages print the comparison symbols; spelled lte / gte here so the
body sanitizer cannot eat the fragment.)

Every row of the new trigger table and the temperature row is a measurement, including the
two the audit could only read off the source: the empty array is a real predicate, and
contains genuinely takes both shapes.

Review round 1 — one FAIL, fixed at 5dabfd2a

Contract review round 1 on e0fdaecb passed every claim at source except one span, and it was
right. skills/objectstack-ai/SKILL.md:189-190 read:

A long-lived stdio transport is a separate opt-in (autoStart: true, or
OS_MCP_SERVER_ENABLED=true).

That names only the deprecated trigger. Verified at source in my own worktree before
touching anything: resolveMcpStdioAutoStart() (packages/types/src/env.ts:333-345) reads
OS_MCP_STDIO_ENABLED first and returns { enabled: true, viaDeprecatedAlias: false };
OS_MCP_SERVER_ENABLED=true falls through to the legacy branch and returns
viaDeprecatedAlias: true, on which MCPServerPlugin.start()
(packages/mcp/src/plugin.ts:234-239) logs "Starting the stdio transport via
OS_MCP_SERVER_ENABLED=true is DEPRECATED — that var now only gates the default-on HTTP
surface. Use OS_MCP_STDIO_ENABLED=true (or the plugin autoStart option)". An author copying
my sentence shipped a boot-time warning and had no way to learn the live spelling.

Now:

The long-lived stdio transport has its own switch and defaults off: autoStart: true,
or OS_MCP_STDIO_ENABLED=true. (OS_MCP_SERVER_ENABLED=true still starts it — deprecated,
and it warns at boot.)

That also states defaults off, which the old wording only implied.

Paid in-file, not by re-wrap. The section's closing sentence ("Your skills' instructions
reach this surface too…") restated the instructions row of the Skill Configuration table in
substance — the exact duplication AI-C-01 exists to remove — and is deleted. 5,481 → 5,476
tokens; the file went down, not up.

Where the error came from, filed as its own card: #14473. The sentence was written from
MCPServerPlugin's class docblock (packages/mcp/src/plugin.ts:112-122), which still
describes the pre-split behaviour — "explicit true additionally auto-starts the stdio
transport" — and disagrees with its own code twelve lines below. That is a code comment
disagreeing with its code, not a spec .describe(), so no spec-side twin is owed. Unassigned,
finding label, dedupe search returned a non-empty result set with nothing open covering it.

Union re-derived after the edit, not reused.
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands on the
patched tree returned a list byte-identical to the 42 from round 1, and all 42 were re-run on
5dabfd2a (with @objectstack/spec and the @objectstack/client-react closure rebuilt first
in the same locked run, since the worktree was re-created from the pushed branch). Same
result: 41 green, 1 NOT MEASURED (check-test-completeness, exit 3), 0 red.

The open question is ruled A — accept the net cut. No second pass.

Labels

skip-changeset — this releases nothing. Checked against the gate's own enumeration
(scripts/check-empty-changeset.mjs:357: "It releases nothing (.github/, .claude/, skills/,
docs/, content/, examples/, tests-only, and the like)"); the diff is skills/**,
content/docs/** and one scripts/ ratchet baseline. No changeset file was written — the
gate's route 2 is the label, and an empty changeset is a real input that stalls a release
silently.

needs:contract-review on this PR and on #14305: falsehood 1 (a retiredKey() tombstone
reclassified from "supported"), falsehood 2 (a CEL carrier claim), the trigger-operator value
shapes, the temperature bound, the MCP tool names, and the skill.tools[] ladder are all
contract-semantics claims. Stays draft until that review lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1