Repository navigation
Description
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 theallowed-toolsfrontmatter.
— 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:
- Install the plugin normally (not
--plugin-dir), so${CLAUDE_SKILL_DIR}resolves to a real
cache path. - In a scratch repo, invoke
/repo-hygiene:cleanand route into a step whose detail lives in a
context/*.md— e.g.preflight, whichSKILL.mdroutes tocontext/preflight.md. - 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. - Observe prompt-or-no-prompt. No prompt ⇒ the placeholder was substituted and matched the
existingBash(${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.
Activity
revert(repo-hygiene): keep context/*.md on the old form pending #2237
fix(plugins): pair seven allowed-tools grants with the invocations th…
kyle-sexton commentedon Aug 11, 2026
kyle-sexton commentedon Aug 11, 2026
decide-lane verdict: DEFER
Consensus (fable + Sol): Do not convert
context/*.mdfrom${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 inallowed-tools.context/*.mdfiles are loaded on demand via Read — whether substitution reaches them is unverified; the docs resolve it neither way.${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 verdictallowed-tools-pairing.test.sh— guard thatcontext/*.mdnever adopt direct${CLAUDE_SKILL_DIR}/scripts/…SKILL.mdpointer + CHANGELOG entrySix
context/*.mdinvocation forms unchanged on${CLAUDE_PLUGIN_ROOT}.PR incoming on
cursor/claude-skill-dir-scope-residual-63e1.kyle-sexton commentedon Aug 11, 2026
PR: #2251 (SHA
a4be77856bd45444d4ff6bc6873c30ec6132e656)docs(repo-hygiene): record CLAUDE_SKILL_DIR scope residual for clean …
docs(repo-hygiene): record CLAUDE_SKILL_DIR scope residual for clean …
docs(repo-hygiene): record CLAUDE_SKILL_DIR scope residual for clean …
kyle-sexton commentedon Aug 12, 2026
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.fix(discovery): retire the unsourced $ARGUMENTS-on-preload claim, seq…
refactor(ai-briefing,repo-hygiene): dissolve restating and recorded c…
feat(scripts): gate skill spokes that name paths through the plugin-r…