fix(repo-hygiene): finish clean's invocation pairing in context/*.md, gated on ${CLAUDE_SKILL_DIR} substitution scope

[kyle-sexton]

The gap

#2225 paired /repo-hygiene:clean's allowed-tools grant with its invocation: SKILL.md now runs
its bundled scripts directly through ${CLAUDE_SKILL_DIR}/scripts/…, and five narrow rules name
those same strings.

The skill's bundled context/*.md files were deliberately left on the old form and still say:

bash ${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/<name>.sh

Files: context/action-router.md, context/clean-batch.md, context/git-branch-cleanup.md,
context/git-tree-reset.md, context/git-tree-reset-batch.md, context/preflight.md.

So the skill carries two invocation forms: SKILL.md in the paired form the grant matches, and
the routed detail files in an interpreter-led form it does not. Commands the model takes from a
context/*.md will not match the new rules and will prompt or fall to the classifier.

This does not weaken #2225's fix — all five granted scripts are invoked from SKILL.md, so the
grant is fully paired for everything it covers. This issue is about finishing the job.

Why it was not just converted

Converting them requires assuming ${CLAUDE_SKILL_DIR} is substituted in a bundled non-SKILL.md
file, and that assumption is unverified. The skills documentation says:

Claude Code substitutes ${CLAUDE_SKILL_DIR} and ${CLAUDE_PROJECT_DIR} in two places: the
skill's markdown content, and Bash rules in the allowed-tools frontmatter.
— https://code.claude.com/docs/en/skills (skills.md:333)

Whether "the skill's markdown content" extends to a bundled context/*.md loaded on demand is
precisely the ambiguity, and the docs resolve it neither way. Note the asymmetry that makes this
non-obvious: ${CLAUDE_PLUGIN_ROOT}'s scope is documented more broadly — plugins-reference scopes it
to "Skill and agent content | Anywhere the placeholder appears" — so the two variables are not
interchangeable here just because both work in SKILL.md.

Failure mode if the assumption is wrong: an unsubstituted body emits a literal
${CLAUDE_SKILL_DIR}/scripts/x.sh, which the Bash tool expands from an unset environment variable
(that variable is not exported into the tool's shell) to /scripts/x.sh. It fails safe — a prompt or
a not-found error, never a wrong action — but it fails silently, which is exactly the defect
class #2225 exists to remove. Shipping it inside that PR would have been the wrong trade.

The empirical test that settles it

One observation, no code change needed:

1. Install the plugin normally (not --plugin-dir), so ${CLAUDE_SKILL_DIR} resolves to a real
   cache path.
2. In a scratch repo, invoke /repo-hygiene:clean and route into a step whose detail lives in a
   context/*.md — e.g. preflight, which SKILL.md routes to context/preflight.md.
3. Temporarily rewrite that one file's invocation to ${CLAUDE_SKILL_DIR}/scripts/preflight.sh
   (direct, unquoted) and let the model run the command it reads there.
4. Observe prompt-or-no-prompt. No prompt ⇒ the placeholder was substituted and matched the
   existing Bash(${CLAUDE_SKILL_DIR}/scripts/preflight.sh:*) rule ⇒ substitution reaches bundled
   context files, and the conversion is safe. A prompt, or a /scripts/preflight.sh: No such file
   error, ⇒ it does not, and the files must stay on ${CLAUDE_PLUGIN_ROOT}.

Checking the emitted command string directly (transcript or OTEL claude_code.tool_decision) is
stronger than inferring from the prompt, if that route is available.

If substitution does reach context files

Convert all six files and extend plugins/repo-hygiene/scripts/allowed-tools-pairing.test.sh to
assert the paired form across context/ as well as SKILL.md — the gate already walks every *.md
under the skill, so this is a scope widening, not new logic.

If it does not

Leave them on ${CLAUDE_PLUGIN_ROOT}, and record the two-form split as an accepted, documented
residual in the convention so the next author does not "fix" it on the same wrong assumption.

Related

• fix(plugins): pair seven allowed-tools grants with the invocations they must match #2225 — the paired body+rule rewrite this defers from (see its "Lane judgment calls" section).
• skills: ${CLAUDE_SKILL_DIR} used in pre-compute but not documented as harness-substituted — three skills may silently report fake pre-compute data #1824 (OPEN) — the neighbouring open question on this same variable: ${CLAUDE_SKILL_DIR} used
  in pre-compute but not documented as harness-substituted, with three skills possibly reporting fake
  pre-compute data. Same root uncertainty about substitution scope; settling one very likely settles
  the other, and the empirical test above would serve both.
• docs/conventions/permission-rule-hygiene/README.md:120-126 — the convention's current statement
  of which variables substitute where.

Provenance

Originating inbox item 20260811-024628-claude-config-audit-permission-grants-defects-and-fleet-grant-hygiene,
ledger .work/handoff-inbox-batch-4/ledgers/I10-permission-grants-fleet.md, half B row B4. Split
out of #2225 by orchestrator decision rather than shipped on an unverified assumption.

[kyle-sexton]

[kyle-sexton]

decide-lane verdict: DEFER

Consensus (fable + Sol): Do not convert context/*.md from ${CLAUDE_PLUGIN_ROOT} to ${CLAUDE_SKILL_DIR}. Record the accepted two-form split as documentation/test residual only.

Rationale

• ${CLAUDE_SKILL_DIR} substitutes in two places per the skills docs (changelog v2.1.69): the skill's markdown content, and Bash rules in allowed-tools.
• Bundled context/*.md files are loaded on demand via Read — whether substitution reaches them is unverified; the docs resolve it neither way.
• Failure mode if converted on the wrong assumption: an unsubstituted body emits a literal ${CLAUDE_SKILL_DIR}/scripts/x.sh, which the Bash tool expands from an unset env var to /scripts/x.sh — fails safe (prompt or not-found), but silently, the defect class fix(plugins): pair seven allowed-tools grants with the invocations they must match #2225 exists to remove.
• ${CLAUDE_PLUGIN_ROOT} is documented more broadly (plugins-reference: anywhere in skill/agent content), so it remains the safe form for context copy-paste examples.

What ships in PR

• plugins/repo-hygiene/skills/clean/reference/invocation-forms.md — accepted two-form split + DEFER verdict
• allowed-tools-pairing.test.sh — guard that context/*.md never adopt direct ${CLAUDE_SKILL_DIR}/scripts/…
• SKILL.md pointer + CHANGELOG entry

Six context/*.md invocation forms unchanged on ${CLAUDE_PLUGIN_ROOT}.

PR incoming on cursor/claude-skill-dir-scope-residual-63e1.

[kyle-sexton]

PR: #2251 (SHA a4be77856bd45444d4ff6bc6873c30ec6132e656)

[kyle-sexton]

Closed by decide-lane DEFER consensus + residual docs/tests in #2251. Context files stay on ; substitution is SKILL.md + allowed-tools only. Overturn condition remains the interactive installed-plugin empirical test named in the issue.