everyinc__compound-engineering-plugin/docs/solutions/skill-design/cross-harness-cross-model-tool-invocation.md

title, category, date, last_updated, module, problem_type, component, severity, applies_when, tags, related_components

title	category	date	last_updated	module	problem_type	component	severity	applies_when	tags	related_components
Cross-harness/cross-model skills drive agent tool calls, not slash commands — describe the capability, verify it by running it	skill-design	2026-07-11	2026-08-23	skills/ce-babysit-pr	design_pattern	tooling	medium	Authoring a skill, once, for multiple agent harnesses and models where the skill needs the agent to invoke a capability (schedule/loop, ask the user, invoke a sub-skill, run background work, drive a browser) Deciding whether to name a specific tool/command in skill prose or describe the capability About to accept an agent's own description of its tool schema as verification A skill can invoke a slash-command-like affordance interactively but not from within its own execution	cross-harness cross-model capability-over-tool tool-vs-slash-command empirical-verification ask-vs-execute portable-skills orchestration	development_workflow tooling

Guidance

1. The unit a skill can drive is an agent tool call, not a user affordance. An agent cannot press keys or type a slash command, so a user-typed command (Cursor's /loop) is not skill-invocable unless the harness also exposes it as a tool (Claude Code's Skill tool can invoke /loop). Treat any "have the skill run /command" step as a smell to verify.

2. The tool surface varies by harness and model, and agents reach for the simplest sufficient tool. Given a capability need with the mechanism unspecified, fresh agents on all four harnesses built a plain background shell loop — none reached for a first-class scheduler, including Grok, whose agent-callable scheduler_create was available and explicitly skipped as overkill. Designing around one "correct" tool is wrong twice: it may not exist elsewhere, and where it does the model may not pick it. Corollary: when the per-invocation work is agent reasoning (invoke a sub-skill, judge feedback), the prose must say so, or the agent takes the shell shortcut that cannot reason.

3. Name the known tool as a short-circuit; describe the capability as the portable fallback. Both, not either — the named tool is speed, the capability description ("a way to run a background process and be woken when it emits a line, without ending your turn"; "the host's blocking-question tool already in the current tool list") is robustness, and degrade explicitly when nothing fits. Do not keep a closed catalog of host-specific names: the next unnamed host repeats the Grok probe-card failure (#1522). Option caps of particular tools may still be named as non-derivable facts.

4. Verify tool behavior by making the agent run the call — its description of its own tools is not evidence. An agent asked to describe its tool schema produces a confident wrong answer as readily as a right one. Only an executed call counts, except for user-facing tools: a blocking question card, permission prompt, or anything that renders to the human is proven by presence in the current tool list (match by capability), because executing it "to see if it errors" is the user-visible failure (#1522). Keep execute-to-prove for non-user-facing tools (plan updates, schedulers, background watches).

The measurement that forced clause 4 (2026-07-16)

Codex was asked to read its own update_plan schema and report allowed step statuses and whether a step can be deleted. It answered: statuses pending, in_progress, completed; no skipped/cancelled status; a step cannot be deleted. Made to actually call update_plan — create three steps, then re-issue the plan with the middle one omitted — it reported: "Remove Step B: SUCCEEDED — resulting plan: Step A, Step C." update_plan takes the whole plan array, so omission deletes. The same probe surfaced facts nobody asked for: Cursor has a native cancelled status, and Cursor deletion requires merge: false (a full-list replace) while rename-then-complete is a targeted merge: true. Rendering matters too: Codex printed ✓ Step C (skipped) — a completion checkmark contradicting its own label.

Question	Codex's self-report	What running it showed
Allowed statuses	pending, in_progress, completed	Same
Skipped/cancelled status?	No	Same — but Cursor does have native cancelled
Can a step be deleted?	No	Yes — omit it from the array

The asymmetry: on the same question, a prior assumption held from training happened to be right while the live agent's self-report was wrong. Neither asking the model nor trusting memory is reliable. Only execution is.

The ask-vs-execute probe shape. "ACTUALLY CALL your <plan/task tool> for each step — do not describe or simulate in prose. 1. Create a plan with 3 steps. 2. Attempt to REMOVE 'Step B' entirely. 3. Attempt to RENAME 'Step C' and mark it completed. For each: did the call SUCCEED or ERROR, and what did the resulting plan actually contain, and what rendered?" The instruction to actually call is load-bearing — without it the agent answers from its schema.

The live-verification technique for cross-harness watches. Publish a controllable external artifact, dispatch a fresh agent per harness with intent-only instructions to watch it and react to a change, then change it to an unguessable value and confirm each caught it unattended. This is how "Codex nohup is reaped when the tool call ends" was caught before shipping.

Provenance of this doc's own claims

This doc predates the ask-vs-execute distinction, so its evidence is mixed. Re-verify by execution before relying on a reported row.

Claim	Provenance
Codex nohup is reaped when the tool call ends; only a runtime-owned handle survives	Executed
Fresh agents on all four harnesses built a plain shell loop; none reached for a scheduler	Executed
Grok's scheduler_create goes unused despite being available	Executed
Cursor's /loop "only loads instructions into context"	Reported — agent self-description; suspect
Codex's CLI exposes no scheduler tool	Indeterminate
Grok's scheduler_create is durable and agent-callable	Indeterminate — likely docs/self-report

When to Apply

Any skill authored once for multiple harnesses/models that needs the agent to invoke a capability. Not needed for a single-harness skill or a capability already proven on the target runtime. The failure is invisible in-repo: confidently-wrong per-harness prose passes every unit test and fails only at runtime on the harness you did not author in.

Related

• Watch-loop skills need a blocked-external terminal state — sibling ce-babysit-pr learning; the self-sustaining loop is where this principle surfaced.
• Bundled script path resolution across harnesses, arguments token is Claude-only in skill bodies — same "don't assume your runtime is universal" root.
• Requested vs verified model identity — the receipt layer of the same epistemics, with the opposite prescription: model identity cannot be settled by execution, so it accepts "unverified" as a terminal state; tool capability can, cheaply, so "unverified" is never acceptable here.
• Scope anti-poll discipline to detached CLI delegates — subagent-dispatch primitives differ per harness, so a portable concurrency rule is written to the least-capable primitive.