Skip to content

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

Closed

Description

@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

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

  1. added
    needs-triageNot yet classified. Floor until a type and one priority tier are set.
    on Aug 11, 2026
  2. self-assigned this
    on Aug 11, 2026
  3. kyle-sexton commented on Aug 11, 2026

    @kyle-sexton
    MemberAuthor
    No description provided.
  4. kyle-sexton commented on Aug 11, 2026

    @kyle-sexton
    MemberAuthor

    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.

  5. kyle-sexton commented on Aug 11, 2026

    @kyle-sexton
    MemberAuthor

    PR: #2251 (SHA a4be77856bd45444d4ff6bc6873c30ec6132e656)

  6. kyle-sexton commented on Aug 12, 2026

    @kyle-sexton
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

needs-triageNot yet classified. Floor until a type and one priority tier are set.

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions