compound-engineering-plugin-mirror/docs/solutions/skill-design/invocation-opt-out-flags-block-sibling-skill-invocation.md

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

title	category	date	module	problem_type	component	severity	applies_when	tags	related_components
Skill opt-out flags block sibling invocation on every host, so a callee skill must stay model-invokable	skill-design	2026-09-08	skills	design_pattern	tooling	high	A skill is authored so that other skills invoke it (a shared writing, commit, review, or simplify step) Deciding whether to set disable-model-invocation or a Codex allow_implicit_invocation policy on a skill to stop it over-triggering A caller skill's prose tells the agent how to reach a sibling skill on a host without a skill tool	skill-invocation disable-model-invocation allow-implicit-invocation cross-harness codex grok activation description-restraint	development_workflow

Context

While planning ce-noslop, a skill that sibling skills invoke at their prose-composition point, the question came up whether it could carry the per-host opt-out flags (disable-model-invocation: true on Claude Code and Grok, policy.allow_implicit_invocation: false on Codex) to keep it from firing on every prose-shaped prompt. The Claude Code docs say the flag prevents the model from "automatically" loading a skill, which reads as description matching only. Whether a sibling's explicit invocation also counts as model invocation was not stated for any host, so it was measured.

Guidance

Any skill that another skill must reach stays model-invokable on every host. Restraint against over-triggering comes from the description's condition, never from an opt-out flag. tests/skill-conventions.test.ts holds REQUIRED_MODEL_INVOKED_CALLEES, the set of skills that pipelines or siblings call; add a new callee there so a later flag fails the suite.

Two facts decide this:

• A sibling's invocation is model invocation on every host. The flag blocks it outright, not only description-triggered loading.
• Codex and Grok have no skill tool. On those hosts a skill is "invoked" when the model reads the SKILL.md at the path the skills catalog lists. The opt-out flag removes the skill from that catalog, so the model has no path to read. A caller skill that forbids reading the target's SKILL.md breaks invocation on those hosts for the same reason: the read is the mechanism.

Write a caller's invocation line to name the capability, not a mechanism: "invoke the ce-noslop skill through this harness's skill mechanism." Do not tell the agent to avoid reading the target's file.

Why this matters

A skill with the flag set looks correct in the authoring session, where the user invokes it by name, and fails silently everywhere a sibling names it: the caller's own rules were deleted in favor of the invocation, so the prose that skill produces loses the rules with no error. The failure only shows in a fresh session on the sibling's path, which ordinary skill evals do not run.

Evidence

Measured 2026-09-07 with six headless runs, one caller skill and one target skill per arm, temp skills under ~/.agents/skills symlinked into ~/.claude/skills:

Host	Command	Mechanism a sibling uses	Open target	Locked target
Claude Code	claude -p	Skill tool	ran, returned its token	Skill tool refused: "cannot be used with Skill tool due to disable-model-invocation"
Codex CLI 0.153.3	codex exec	reads the catalog-listed SKILL.md	ran, returned its token	absent from the skills catalog, so no path to read
Grok CLI	grok --prompt-file	reads the catalog-listed SKILL.md	ran, returned its token	absent from the catalog

"Locked" meant disable-model-invocation: true in frontmatter plus policy.allow_implicit_invocation: false in both the frontmatter and the temp skill's own OpenAI agent manifest (a file named openai.yaml under its agents directory; the temp skills were removed after the run). The Claude Code skills documentation states the flag blocks the Skill tool as well as automatic loading; the Codex skills catalog prompt lists only skills the policy allows; the Grok skills guide says the flag means "only your slash command runs the skill".

A first round on Codex and Grok failed for the wrong reason: the caller forbade reading the target's SKILL.md, and on those hosts that read is the invocation. That is the second fact above.

When to apply

• Before setting either flag on any skill, check whether a sibling or pipeline names it; if so, the flag is wrong and the description carries the restraint.
• When a caller skill's prose describes how to reach a sibling, describe the capability and leave file reads allowed.
• When a skill eval must prove sibling invocation, run it in a fresh host session with both skills installed, on Codex and Grok as well as Claude Code; the eval cell that loads one skill per run cannot show it.

Examples

Wrong, in a callee's frontmatter:

disable-model-invocation: true

Right, in the callee's description: state the condition that should fire it ("Use when text is handed over to fix ... and when a skill about to compose a PR body, plan, finding, or reply names this skill") and add the skill to REQUIRED_MODEL_INVOKED_CALLEES.

Wrong, in a caller: "Invoke the target skill; do not open its SKILL.md with a file-reading tool." Right: "Invoke the <target> skill through this harness's skill mechanism."