Skip to main content

ADR 0046: Keep Skill Launcher Prompts Concise

Status​

Accepted.

Context​

Each packaged skill has two different instruction surfaces. SKILL.md is the agent-facing workflow loaded when the skill runs. agents/openai.yaml supplies UI metadata and a starter prompt used to invoke that skill. The plugin manifest also supplies a plugin-level starter prompt for the primary route.

STAGE had copied route rejection, zero-inspection, preservation, and stopping rules into all three starter prompts. The copies made a launcher prompt more than one hundred words long, consumed context a second time after skill loading, and forced tests to preserve two policy sources. A future policy edit could therefore pass in one surface while silently drifting in the other.

The Codex skill-authoring contract describes interface.default_prompt as a short, typically one-sentence example that explicitly invokes the skill. It is not a second skill body.

Decision​

Keep each agents/openai.yaml default prompt to one short sentence that:

  • invokes the plugin-qualified skill name;
  • states the route-specific outcome; and
  • leaves detailed authority, stopping, evidence, and execution policy in the corresponding SKILL.md.

Keep the plugin-level interface.defaultPrompt equally concise and positive: name ordinary delivery as the default, then distinguish optional routes without copying their prohibited-artifact lists or execution policy.

Tests should establish launcher shape and size separately from workflow behavior. Policy tests continue to assert the canonical skill body, specification, method, and failure guidance. A behavior probe remains appropriate when a policy change could alter model routing; duplicating the policy in a starter prompt is not a substitute for that probe.

Consequences​

  • Explicit skill invocation remains clear while consuming less repeated context.
  • Workflow policy has one packaged agent-facing source instead of two.
  • Launcher and skill-body tests can fail for their actual responsibilities.
  • A skill-body regression can no longer be masked by a redundant launcher copy, so material routing changes may require an opt-in behavior probe.
Last updated on