Compile target-aware Skills with host frontmatter and interpolation

[ScriptedAlchemy]

Summary

Provide one expressive Skill authoring surface that Agent Bundle can compile into
the exact skill and plugin artifacts supported by each selected agent host.

Authors should be able to use portable Agent Skills content, host-specific
frontmatter and sidecar metadata, runtime placeholders, plugin-path variables,
arguments, resources, and generated Markdown without manually maintaining one
SKILL.md tree per host.

This is an outcome requirement, not a commitment to one implementation. MDX,
TSX, a custom Rslib/MDX loader, an Agent Document renderer, or a simpler
compiler-owned transform are all valid avenues to evaluate.

Problem

Agent Bundle currently normalizes one skill directory and copies or generates
the same skills/<name>/SKILL.md tree for every selected target. This works for
the portable Agent Skills core, but the hosts have materially different native
surfaces:

• Claude Code extends Skill frontmatter with arguments, invocation policy,
  model/effort selection, forked context, agents, background execution,
  tool restrictions, path filters, shell injection, and skill-scoped hooks.
• Codex keeps SKILL.md deliberately small and expresses UI, invocation policy,
  and dependencies in agents/openai.yaml; it has no documented Skill Markdown
  interpolation engine. Codex plugin hooks expose PLUGIN_ROOT/PLUGIN_DATA
  variables, while deprecated custom prompts have a separate argument syntax.
• Cursor extends Skill discovery and frontmatter with path filters and explicit-
  only invocation, but its documented ${VAR} interpolation belongs to plugin
  configuration rather than Skill Markdown. It also has separate native rules,
  commands, hooks, agents, and a workspaceOpen plugin-loading surface.

A single superset YAML document is not a safe solution. Several portable,
upload, plugin, and generated-artifact schemas reject unknown fields rather than
promising to ignore them. Conversely, reducing every Skill to the portable
intersection prevents authors from using important native capabilities.

Required authoring outcome

Support one canonical Skill source with:

• the portable Agent Skills fields and Markdown body;
• optional typed target-specific fields and sidecar documents;
• canonical references to arguments, skill root, plugin root, plugin data,
  project/workspace root, session identity, and other host runtime values;
• referenced scripts/, references/, assets/, and arbitrary additional
  Skill resources;
• static Markdown authoring and a rendered authoring form suitable for dynamic
  composition (for example MDX or TSX);
• target selection and capability requirements;
• deterministic diagnostics when a requested behavior cannot be expressed on a
  selected host.

Illustrative only:

export const skill = defineSkill({
  name: 'review',
  description: 'Review a change and report actionable findings.',
  targets: {
    claude: { model: 'sonnet', context: 'fork' },
    cursor: { paths: ['src/**'] },
    codex: {
      interface: { displayName: 'Review change' },
      policy: { allowImplicitInvocation: true },
    },
  },
});

export default function ReviewSkill() {
  return (
    <>
      <h1>Review the change</h1>
      <p>Review <Skill.Arguments /> in <Skill.ProjectRoot />.</p>
      <p>Use <Skill.Resource path="references/checklist.md" />.</p>
    </>
  );
}

The source syntax above is not prescribed. It demonstrates the information the
compiler must be able to represent.

Compiler and projection requirements

1. Parse the source into a canonical Skill IR that retains portable metadata,
   host extensions, the rendered document, resource references, runtime
   placeholders, provenance, and capability requirements.
2. Lower the IR through the existing target adapter/capability system. Emit only
   fields and auxiliary documents legal for that host; never depend on unknown
   fields being ignored.
3. Preserve runtime values as runtime placeholders. For example, a canonical
   argument or plugin-root reference may lower to Claude's $ARGUMENTS or
   ${CLAUDE_PLUGIN_ROOT}, a legal Codex hook/plugin variable in the correct
   document, or an explicit unsupported diagnostic. Do not resolve these values
   at build time and do not leak one host's syntax into another host's output.
4. Cover interpolation across the whole plugin surface, not only the Skill body:
   Skill arguments, plugin configuration, MCP arguments/environment/working
   directory, hooks, commands, prompts, resources, and host sidecar documents
   must share one typed capability and token model where their semantics align.
5. Compile a rendered source into ordinary static SKILL.md plus resources.
   Evaluate MDX/TSX compiled to a server component, rendered into an Agent
   Document and projected to Markdown, against a smaller Markdown-AST transform.
6. The build may share identical bytes across hosts, but differing native
   metadata or placeholder syntax requires target-specific documents or an
   equivalent install-time projection. Do not claim one shared file is valid
   without proving semantic identity.
7. The Agent Bundle artifact planner owns final destinations such as
   skills/<name>/SKILL.md, atomic staging, manifests, validation, and output
   provenance. A loader may compile source modules or assets, but must not bypass
   target planning or create untracked files.
8. Skill sources, imports, resources, and capability schemas participate in
   watch invalidation and content/effective-behavior digests.
9. inspect and Workbench show the authored source, each generated host
   document, placeholder lowering, omitted/degraded features, and the evidence
   behind every capability decision.
10. Existing hand-authored portable SKILL.md directories remain a supported
    pass-through source and do not require React, MDX, or JavaScript.

Static build versus Flight

Skills are static install artifacts. A rendered Skill source may reuse the same
React-owned Agent Document renderer and Markdown projector introduced by #96,
but it does not need to ship JavaScript or send a Flight stream to a client.
The build can execute the compiled server component, await its final document,
project Markdown, and emit the result.

Current hooks likewise do not use Flight: they are generated Node wrappers plus
host-native manifests and codecs. Semantic event routes may later use #96 to
render hook/event results, but this issue must not describe that future
composition as current integrated behavior.

Acceptance criteria

• One source produces schema-valid Codex, Claude Code, and Cursor Skill/plugin
  artifacts that exercise at least one genuinely different native capability
  per host.
• Portable-only Skills remain byte-stable when no host extension or canonical
  placeholder requires target-specific output.
• Claude arguments and skill/plugin-root variables lower and execute in a real
  Claude plugin installation.
• Codex agents/openai.yaml metadata/policy/dependencies lower separately from
  SKILL.md and are verified in a real Codex installation.
• Cursor path/invocation fields and plugin configuration variables lower to
  their documented native locations and are verified in a real Cursor plugin
  installation.
• Selecting a host without an equivalent for a required field or placeholder
  fails before publication with a precise diagnostic and recovery options.
• Unknown host fields are never silently copied into another host's closed
  frontmatter or manifest schema.
• Static Markdown, rendered Skill source, resources, watch rebuilds, packed
  publication, install, discovery, explicit invocation, and implicit activation
  have end-to-end fixtures.
• Generated artifacts contain no authoring-only MDX/TSX modules and include
  exact source/capability provenance.

Implementation questions to resolve

• Should the rendered source convention be SKILL.mdx, SKILL.tsx, or both?
• Is the best implementation an Rslib/MDX loader feeding a canonical IR, a
  dedicated Skill build profile, or the existing compiler-owned generated-write
  path with a renderer? Compare watch behavior, source maps, output control,
  dependency tracking, and multi-target lowering.
• Can the combined multi-host plugin retain one shared skills/ tree when
  outputs differ, or must lifecycle installation select/copy a host-specific
  tree? Prove actual host discovery and precedence before choosing.
• Which placeholders are semantically portable, which require target-specific
  namespaces, and which have no honest cross-host equivalent?
• How should native fields that affect one invocation/turn be distinguished from
  persistent session or plugin behavior?

Design references

• Agent Skills specification
• Claude Code Skills
• Claude Code plugin reference
• Codex: build skills
• Codex: package plugins
• Cursor Skills
• Cursor plugin reference
• Agent Bundle current Skill parser
• Agent Bundle current rendered-Skill compiler
• Agent Bundle current target artifact planner
• Agent Bundle pinned Agent Skills schema

Stack position

• Child of Compile capability-aware host component bundles #100: capability-aware host component bundles.
• Uses Compile filesystem routes into the Agent Bundle meta-framework #93's compiler IR and capability-state contract.
• May reuse Build a real RSC Agent Document renderer with streaming semantics #96's final Agent Document/Markdown projection, but static portable
  Skill compilation must not require a live Flight client.
• Generated host-specific layouts and install-time selection feed Add safe managed lifecycle for generated host bundles #101 managed
  lifecycle.
• Source/generated comparison and invocation replay feed Add an interactive Agent Workbench with local host discovery and lifecycle replay #105 Workbench.

[ScriptedAlchemy]

Progress — v1 design slice landed as #185

PR: #185
Commit: dbbe347f3 (feat(skills): compile a canonical Skill IR with typed host tokens)
Branch: wave4/108-skill-ir (rebased onto origin/main at 5cc783ee0)

Scope (this PR)

Canonical Skill IR, one plugin-surface token registry, closed per-host lowering for Claude / Cursor / Codex / portable, and static projection through the existing SKILL.tsx/SKILL.ts path. Fixture tests + inspect-visible layout decision only. Not real-install acceptance (that still rides #100 stage 3).

IR / token model

One source → IR retaining portable Agent Skills metadata + Markdown body, typed Claude / Cursor / Codex extensions, sidecars, resource refs, runtime placeholders, provenance, and diagnostics. Hand-authored portable SKILL.md is a byte-stable copy when no extension or placeholder requires target-specific output.

Canonical tokens (same bytes as existing pathTokens where they overlap):

Id	Spelling
arguments	agent-bundle:token:arguments
skillRoot	agent-bundle:token:skill-root
pluginRoot	agent-bundle:path:plugin-root
pluginData	agent-bundle:path:plugin-data
projectRoot	agent-bundle:path:workspace-root
sessionIdentity	agent-bundle:token:session-identity

Build-time substitutes syntax only. Classification is per host × document kind: portable / namespaced / none. AB3008 when a selected target cannot express a required token; AB3009 if foreign host syntax leaks.

Skill-Markdown lowering

Token	Claude	Codex	Cursor	Portable
arguments	$ARGUMENTS	none → AB3008	none → AB3008	none → AB3008
skillRoot	${CLAUDE_SKILL_DIR}	none	none	none
pluginRoot	${CLAUDE_PLUGIN_ROOT}	none in SKILL.md	none in SKILL.md	none in SKILL.md
pluginData	${CLAUDE_PLUGIN_DATA}	none in SKILL.md	none	none in SKILL.md
projectRoot	${CLAUDE_PROJECT_DIR}	none	none in SKILL.md	none
sessionIdentity	${CLAUDE_SESSION_ID}	none	none	none

Plugin-config / hooks / MCP keep the existing host expanders; the registry is the shared source of those tables. Pins: Claude Code 2.1.250, Codex 0.147.0, Cursor 2026-08-28 / cursor/plugins@070189284e702e8a4d2e3cc8913994b204c5337a, Agent Skills 69ef37e9424c0a7ea9dd2293b559e43ec8176379. Closed output schemas in src/schemas/skill-hosts/ (additionalProperties: false).

Rendered-form decision

Keep SKILL.tsx / SKILL.ts. Already compiles at config-load via jiti + renderElementToMarkdown, no live Flight client, already in watch/digest. MDX would add a second toolchain; a Markdown-AST compiler cannot express defineSkill + Skill.* composition. Documented in the PR.

defineSkill / Skill.* are identity helpers. Host syntax is applied only during lowering.

Shared vs per-host skills/ tree

Inspect-visible (skillTreeLayout.decision: shared | per-host-required, feeds: '#101'). Not hard-committed. Standalone targets write skills/<name>/SKILL.md in that artifact root. Composite plugin writes the portable intersection when Claude/Codex documents differ.

Files

New: src/skills/{tokens,ir,parse-ir,lower,inspect,define,index}.ts, src/schemas/skill-hosts/*, tests/skill-ir.test.ts, .changeset/skill-ir-token-model.md (minor).

Wired: config/{skill,normalize,validate,rendered-skill}.ts, adapters/types.ts (skill emission tail only — event/hook files untouched for Lane A), build/validate-artifact-skills.ts, core/types.ts, public defineSkill / Skill / skillTokenSpellings / classifySkillToken.

Diagnostics: AB3006 unknown field, AB3008 no-equivalent token, AB3009 leak, AB3010 closed-schema fail.

Scoped results

• skill-ir.test.ts (12 cases) pass
• rendered-skills, agent-skills-schema, skill-document-service, config, normalization pass
• cursor-adapter, manifest, provenance pass (30)
• rslint on touched files: 0 issues
• capabilityRevision / sha fields unchanged

Still needed (rides #100 stage 3)

Real Claude plugin install proving $ARGUMENTS / ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_SKILL_DIR} in a live session; Codex agents/openai.yaml install + interface/policy/dependencies; Cursor paths/invocation + plugin-config vars; host-side confirmation of the #101 shared-vs-per-host tree.

[ScriptedAlchemy]

Merged. #185 squash-landed as 6baf597b1 on main.

6baf597