docs(conventions): align permission-rule-hygiene quotes with current skills page (row 156 dependency pass)

[kyle-sexton]

Summary

Executes row 156's owed dependency pass (the optional follow-up on #1989): the page-level DONE close of the Extend Claude with skills roster row had checked only plugins/playbooks/skills/fable-5/context/verification.md, owing a pass over the other citing files.

Enumeration: re-derived by git grep -E 'code\.claude\.com/docs/en/skills([^a-z-]|$)' at origin/main 958f9579 — 36 files / 59 citing lines (the row's count of 34 was taken at 81c0297d87; main has moved). The live page was re-fetched raw (HTTP 200, 82,668 B) and has changed since the row's 2026-08-06 baseline (78,513 B, MD5 differs), so every citation was checked against the current page.

Result: 35 of 36 files conformant; 2 stale claims, both in docs/conventions/permission-rule-hygiene/README.md, fixed here:

• ${CLAUDE_SKILL_DIR} v2.1.129 floor dropped — the sentence attributed both substitution version floors to the skills page; the live page now documents only the ${CLAUDE_PROJECT_DIR} floor ("The ${CLAUDE_PROJECT_DIR} substitution requires Claude Code v2.1.196 or later"). The 2.1.129 claim is no longer supported by its cited source.
• allowed-tools grant quote re-quoted — the page no longer says the grant holds "while the skill is active"; it now reads "grants permission for the listed tools during the turn that invokes the skill" and "The grant clears when you send your next message". Semantic upstream change (turn-scoped, not skill-active-scoped); the anti-pattern-3 argument survives strengthened. Bullet lead re-worded "skill-scoped" → "turn-scoped" to match.

Notable conformant checks (representative): namespace claim verbatim at live page (3 citing files); invocation-control table "Description not in context" (skill-quality scripts/tests/CHANGELOG, discipline, claude-config criteria); 1,536-char truncation verbatim; context: fork / agent / lifecycle / 5,000-token compaction quotes verbatim; ${CLAUDE_PLUGIN_ROOT} still absent from the page (the convention's negative claim holds); v2.1.145 / v2.1.215 / v2.1.216 bundled-skill claims verbatim (testing, verification, review, playbooks). The spec-validation absence claim in verification.md still holds: the commands page now has 14 [Skill] rows and one [Workflow] row (/deep-research); none is spec-validation, so the row's recheck trigger has not fired. A repo-wide sweep for the two stale phrases found no other live occurrence (remaining hits are disallowed-tools prose matching the live page, historical CHANGELOG entries, and one unrelated docs/PLUGIN-PHILOSOPHY.md sentence that is the repo's own prose, not a docs quote).

No plugin versioned surface is touched — repo docs only, no version bump.

Test plan

• Live page re-fetched raw and each of the 59 citing lines checked against it (quotes grepped verbatim; anchors resolved against the live heading list)
• Repo-wide git grep sweep for 2\.1\.129 and while the skill is active — no other live occurrence
• markdownlint-cli2 on the changed file — 0 errors
• Both retained quotes verified verbatim substrings of the live page

Related

No linked issue — this is the optional row-156 dependency pass tracked under umbrella #1989 (kept open deliberately; no closing keyword).

🤖 Generated with Claude Code

https://claude.ai/code/session_01HbtPzLRe1yBavNpsmv5Tum

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 2m 7s —— View job

---

Review complete

• Gather context (diff, CLAUDE.md, REVIEW.md)
• Independently re-verify the two quote changes against the live skills page
• Check repo-wide sweep claim (no other occurrences of stale phrases)
• Check markdownlint claim
• Post findings

Scope

Single-file docs edit, docs/conventions/permission-rule-hygiene/README.md (+7/-6). This is in the fresh-docs-mandate scope (documented harness behavior — substitution version floors and allowed-tools grant scope). I independently re-fetched https://code.claude.com/docs/en/skills (fresh WebFetch this session, not the PR author's claimed re-fetch) and checked both edits directly against it — both are correct:

1. ${CLAUDE_SKILL_DIR} v2.1.129+ floor removed (L83) — confirmed: the live page's substitutions table (${CLAUDE_SKILL_DIR} / ${CLAUDE_PROJECT_DIR} rows) and surrounding prose state only "The ${CLAUDE_PROJECT_DIR} substitution requires Claude Code v2.1.196 or later" — no version floor for ${CLAUDE_SKILL_DIR} anywhere on the page. A repo-wide grep -n "2\.1\.129" outside CHANGELOGs also came up empty, matching the PR's sweep claim.
2. allowed-tools grant re-quoted turn-scoped (L97-101) — confirmed: the live page (under "Pre-approve tools for a skill") reads verbatim "grants permission for the listed tools during the turn that invokes the skill, so Claude can use them without prompting you for approval. The grant clears when you send your next message, ... It does not restrict which tools are available: every tool remains callable...". All three excerpted fragments in the PR are exact substrings. grep -n "while the skill is active" repo-wide surfaces only unrelated disallowed-tools prose (still accurate per the live page's disallowed-tools row) and CHANGELOG history — no live occurrence of the retired phrase remains, matching the PR's claim.

Not independently verified (author-claimed only): the markdownlint-cli2 0-errors claim — the binary isn't installed in this sandbox and installing it required an approval I couldn't obtain, so I could not run the linter myself. A quick manual read of the diff didn't turn up obvious Markdown issues, but that's not equivalent to running the linter.

Findings

One non-blocking inline nit posted on L99-100: splicing three quoted source fragments as grammatical objects of "It" is a bit strained since two of the three are themselves full sentences in the source. Purely a prose-polish suggestion — the content is accurate and the quotes are verbatim.

No correctness, architecture, or maintainability issues found otherwise. The PR is a well-scoped, well-cited docs correction; no versioned plugin surface is touched, consistent with the PR description.
· Branch

[github-actions]

Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 2m 13s —— View job

---

Review complete

• Gather context (diff, CLAUDE.md, prior review thread)
• Review new commit against prior inline nit (prose-splice fix)
• Re-verify quote changes still accurate against live skills page
• Check for new issues introduced by the fix commit
• Post findings

What changed since my last review

Commit 9883e9c addresses the prose-splice nit from my previous review (0a5636b's L99-100): it splits the three spliced quotes into standalone clauses. I re-fetched https://code.claude.com/docs/en/skills fresh this session (not relying on the PR author's or my prior claimed fetch) and re-checked both edited passages.

1. ${CLAUDE_SKILL_DIR} v2.1.129 floor removal (L79-85) — unchanged since the last review, still confirmed accurate: the live "Available string substitutions" section states only "The ${CLAUDE_PROJECT_DIR} substitution requires Claude Code v2.1.196 or later" with no floor given for ${CLAUDE_SKILL_DIR}, and ${CLAUDE_PLUGIN_ROOT} does not appear on the page at all.

2. allowed-tools grant re-quoted (L98-103) — the fix commit resolved the grammatical splice, but in doing so replaced the joining commas with periods inside the quotation marks. The live page's actual sentences don't end where those periods now imply: "...invokes the skill**,** so Claude can use them without prompting you for approval." and "...your next message**,** even though the skill content stays in context; invoking the skill again re-applies it for that turn." Posted as an inline nit with a suggested fix (semicolons instead of sentence-final periods) — this is a quoting-precision issue, not a factual one; the semantic content of both fragments is still accurate.

Findings

One non-blocking inline nit on L99-101: the two re-quoted fragments now close with a period inside the quotation marks at a point where the live source actually has a comma and continues the sentence — overstating quote fidelity in a doc whose entire premise is verbatim-checked citations. Ironically this traces back to my own prior suggested wording; flagging it now since I independently re-verified the exact source punctuation this pass.

No other issues found. Scope, sourcing methodology, and the two substantive claim corrections remain sound; no versioned plugin surface is touched.

Not independently verified (author-claimed only): markdownlint-cli2 0-errors claim — not installed in this sandbox.
· Branch

[claude]

Claude finished @kyle-sexton's task in 2m 1s —— View job

---

Review complete

• Gather context (diff, CLAUDE.md, prior review threads)
• Review latest commit (54bb17f) against my prior punctuation-fidelity nit
• Re-verify quote changes against live skills page
• Post findings

What changed since my last review

Commit 54bb17f addresses the punctuation-fidelity nit from my previous review (9883e9c's L99-101): the joining comma before the first quoted fragment's closing period was replaced with a semicolon placed outside the quotation marks, so the quote no longer implies a source-terminal period where the source actually continues with ", so Claude can use them without prompting you for approval."

I re-fetched https://code.claude.com/docs/en/skills fresh this session (independent of the PR author's and my own prior claimed fetches) and checked the current wording at L97-101 against the live "Pre-approve tools for a skill" section, which reads verbatim:

"The allowed-tools field grants permission for the listed tools during the turn that invokes the skill, so Claude can use them without prompting you for approval. The grant clears when you send your next message, even though the skill content stays in context; invoking the skill again re-applies it for that turn. It does not restrict which tools are available: every tool remains callable, and your permission settings still govern tools that are not listed."

Fragment 1 ("...invokes the skill") — now correctly un-punctuated at the closing quote, matching the source's comma-continuation. Fixed, confirmed accurate.

Fragment 3 ("does not restrict which tools are available") — unchanged, still verbatim. Confirmed accurate.

One remaining subtlety (FYI only, not requiring further action): fragment 2, "The grant clears when you send your next message.", closes with a period inside the quote. In the specific paragraph being cited above, that clause is not sentence-final in the source — it continues with a comma into "even though the skill content stays in context...". However, the identical wording does appear as a complete, period-terminated sentence in two other places on the live page: the allowed-tools frontmatter-reference table row, and the "skill content lifecycle" paragraph. So the quote is a verbatim, sentence-final match to those other locations, even though it splices slightly across sentence boundaries relative to the specific paragraph the bullet is citing. Given this has already gone through two rounds on the same three fragments, I'm flagging this purely as an FYI rather than pushing for a third — it's a genuinely arguable case, the semantic content is accurate either way, and I don't think it warrants another edit cycle.

Findings

No blocking issues. The ${CLAUDE_SKILL_DIR}/${CLAUDE_PROJECT_DIR} version-floor correction (L79-85, unchanged since my first review) remains confirmed accurate against the live page — no version floor exists for ${CLAUDE_SKILL_DIR} anywhere on the page, and ${CLAUDE_PLUGIN_ROOT} still does not appear on it.

Not independently verified (author-claimed only): the markdownlint-cli2 0-errors claim — the binary isn't installed in this sandbox.

Scope, sourcing methodology, and both substantive claim corrections remain sound. No versioned plugin surface is touched, consistent with the PR description.
· Branch