refactor: tighten the 10 worst skill-listing descriptions toward the shared budget

[kyle-sexton]

No linked issue

Summary

Executes issue #2022's option 2 (tighten the worst descriptions): a mechanical tighten pass over the ten skill-listing entries above 1,000 chars, trimming explanatory prose from each SKILL.md frontmatter description toward the trigger phrases that earn their keep. The issue stays open — the operator records the option decision there separately.

Fix

Tightened the ten worst description fields, preserving every single-quoted trigger phrase verbatim (skill-quality check 3's tracked surface):

Skill	Before	After	Saved
source-control/babysit-loop	1,468	931	537
claude-config/audit-instructions	1,197	948	249
docs-hygiene/audit-derivability	1,161	876	285
session-flow/running-retro	1,116	869	247
session-flow/reconcile	1,072	837	235
adhd/clarify	1,058	766	292
architecture/improve	1,057	900	157
discipline/script-the-deterministic-work	1,054	872	182
planning/audit-answers	1,028	899	129
discipline/reuse-or-replace	1,022	836	186
Total	11,233	8,734	2,499

Pooled full-install aggregate (check-listing-budget.sh plugins/*/skills, measured post-change on this branch): 85,650 chars over 136 listing-eligible skills across 62 roots (~10.7x the 8,000-char documented default). The issue's baseline (86,499 / 134 skills / 61 roots) was measured on an older main (19a3f7b3); on this branch's base (d894e3b3, which added skills since) the pre-change aggregate derives to 88,149, so this pass removes 2,499 chars. Still advisory-only and well over the default budget — this is exactly the no-structural-change remediation the issue's option 2 scoped.

Each touched plugin gets a patch version bump + CHANGELOG entry: adhd 0.3.2, architecture 0.4.3, claude-config 0.25.1, discipline 0.10.2, docs-hygiene 0.9.6, planning 0.28.3, session-flow 0.20.1, source-control 0.48.1. generate-catalog.mjs / generate-cheatsheet.mjs re-run: no diff (neither embeds skill frontmatter descriptions).

Fresh-docs citation (frontmatter is a contract surface): verified against the current official Skills page, https://code.claude.com/docs/en/skills, fetched this session — description is the auto-invocation trigger surface ("Claude uses this to decide when to apply the skill"), the combined description + when_to_use entry truncates at 1,536 chars, the shared listing budget defaults to 1% of the model's context window (skillListingBudgetFraction / SLASH_COMMAND_TOOL_CHAR_BUDGET), and the page's own remedy is "trim the description and when_to_use text at the source: put the key use case first."

Verification

• Trigger preservation (check 3 semantics, vs origin/main d894e3b3): extracted every single-quoted trigger phrase from each base description with the plugin's own skill_frontmatter::extract_triggers and comm -23-diffed against the new descriptions — zero lost triggers across all ten skills (including non-"Use when" quoted spans such as 'autopilot', '--merge c3-this-run', '/planning:devils-advocate').
• skill-quality gate (check-skill.sh, CHECK_SKILL_SKIP_MARKDOWNLINT=1 per the repo's own CI division of labor): all 10 touched skills PASS (rc=0). Only advisory WARNs remain, all pre-existing and body-level, untouched by this PR: soft line-count targets (babysit-loop 495, audit-instructions 398, running-retro 240, clarify 240) and two fresh-eyes-declaration heuristics (audit-instructions criteria.md, audit-derivability SKILL.md:122). Some gate runs completed after the branch commit landed, where check 3's default HEAD comparison is trivially clean — the comm-based trigger verification above ran against origin/main explicitly, and CI's check-changed-skills.sh re-verifies against the merge base.
• Listing budget: check-listing-budget.sh plugins/*/skills re-run post-change — output quoted above.

Related

Refs #2022 — this PR implements its option 2; the operator records the decision and closes the issue separately.

🤖 Generated with Claude Code

[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 1m 15s —— View job

---

Security review

• Gather context (gh pr diff / local diff against base d894e3b, read changed files)
• Understand the request (security review scoped to this PR's changed files)
• Review changed SKILL.md / plugin.json / CHANGELOG.md files for security issues
• Post findings

Scope of this PR: 26 files, all either (a) one-line frontmatter description edits in 10 SKILL.md files, (b) plugin.json version bumps (no other field changed), or (c) CHANGELOG.md additions. No workflow files, hooks, MCP configs, permissions, scripts, or skill bodies are touched — this is a text-only trim of the frontmatter listing description toward a character budget.

Specific check performed: plugins/source-control/skills/babysit-loop/SKILL.md is the one touched skill with real authorization semantics (merge-authority tiers, the autopilot + --merge c3-this-run escalation exception). The tightened description drops some qualifying clauses that were in the old description (e.g. "never a config value, never model-supplied, never inferred from a drain/merge phrasing"). I verified this isn't a behavioral regression: the frontmatter description is only the auto-invocation trigger/listing surface (per the Skills docs cited in the PR), not an enforcement mechanism — and the skill body (untouched by this diff) still fully carries the safeguard: the paired-token requirement, the "never composed by a model on the caller's behalf" language, the deterministic C4/C5 floor, and the pre-escalation dispatch reference (lines 71–143 of babysit-loop/SKILL.md). No functional or authorization-boundary change.

Also checked the plugin.json diffs — only the version field changed in each; description, author, permissions, and MCP/hook config are untouched. CHANGELOG.md entries are plain prose, no injected content.

Conclusion: no security issues found. This PR has no security-relevant surface — it's a mechanical, additive-only doc trim with no logic, workflow, config, or authorization changes.

[claude]

Claude finished @kyle-sexton's task in 4m 8s —— View job

---

Review: PR #2054

• Gather context (diff, CLAUDE.md, REVIEW.md)
• Review each tightened SKILL.md description for trigger-phrase preservation and accuracy
• Check plugin.json version bumps + CHANGELOG entries for consistency
• Verify claims (listing budget script, skill-quality gate) are labeled author-claimed vs independently verified
• Post findings

What I checked

I diffed the PR commit against its direct parent (d894e3b, matching the PR's declared 26-file/94+/18- footprint exactly) and reviewed all ten touched SKILL.md descriptions plus the accompanying plugin.json bumps and CHANGELOG.md entries.

Independently verified:

• The 26 changed files match the PR's own file list exactly; no unrelated content is swept in.
• For every one of the 10 touched skills, I extracted the Use when: '...' trigger phrase lists from both the old and new descriptions and manually diffed them — zero trigger phrases were lost in any of the ten (I re-derived this myself rather than trusting the PR body's own comm-based claim, which independently checks out).
• Spot-checked the claimed per-skill char savings (clarify: 1,058→766 claimed; babysit-loop: 1,468→931 claimed) by measuring the raw description line length before/after with wc -c — the deltas match the PR table exactly (537 and 292 chars saved respectively), confirming the savings figures are real, not fabricated, even though my raw byte counts differ slightly from the table due to prefix/quote handling.
• Each touched plugin's plugin.json version bump and CHANGELOG.md entry line up correctly with the actual skill(s) changed in that plugin, and the char-count deltas cited in the CHANGELOG entries match the PR table.
• plugins/source-control/.claude-plugin/plugin.json's own top-level description field (not touched by this PR, correctly out of scope) still carries the full merge-authority language, so the plugin-catalog-level description isn't affected by this trim — only the skill-level frontmatter used for auto-invocation is.

Not independently verified (author-claimed only): the pooled full-install aggregate (85,650 chars / 136 skills / 62 roots) from check-listing-budget.sh, and the check-skill.sh gate PASS results — the sandbox in this review lane blocks executing repo scripts directly, so I could not re-run either. Treat those as author-claimed.

Finding

One inline comment on plugins/source-control/skills/babysit-loop/SKILL.md: the merge-authority sentence in that description lost several safety-relevant qualifiers (the fail-closed default, the "raises bind only from the tracked config seam" invariant, the anti-spoofing clause on the c3-this-run exception, and the independent-subagent-resolves-blockers-first detail) that the other nine trims don't have an analog for, since this is the one skill in the batch that can autonomously merge PRs. The full detail is preserved in the skill body and the loop-lane convention doc, so it's not a functional regression, but it's worth a second look at whether the frontmatter description — the surface read before the model decides to invoke — should keep a little more of that framing.

Everything else — trigger-phrase preservation, version/changelog hygiene, and scope — looks correct and mechanical, matching the PR's description of itself.

[github-actions]

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

[kyle-sexton]

Finding accepted and fixed in 29babd4: all four invariants restored in compact form (fail-closed human-only default, tracked-seam-only standing raises, the c3-this-run anti-spoofing clause, and the independent frontier-tier resolver). The entry stays well under both the per-skill cap and its pre-trim size.

[claude]

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

---

Security review

• Gather context (gh pr diff 2054, read all changed files)
• Review changed SKILL.md / plugin.json / CHANGELOG.md files for security issues
• Check the babysit-loop fix commit (29babd4) that restored the dropped safety invariants
• Post findings

Scope confirmed: 25 files, all either (a) one-line frontmatter description edits in 10 SKILL.md files, (b) plugin.json version-only bumps, or (c) CHANGELOG.md prose additions. No workflow files, hooks, MCP configs, permissions, or scripts are touched, and no skill bodies are touched — this remains a text-only trim of the frontmatter listing description toward a character budget.

Re-checked plugins/source-control/skills/babysit-loop/SKILL.md (the one skill in this batch with real merge-authority semantics, and the subject of the prior review's finding): commit 29babd4 restored all four safety-relevant qualifiers into the description in compact form —

• fail-closed default ("human-only until the target repo's tracked config adopts the lane")
• the anti-widening invariant ("standing rung raises bind from the tracked config seam only")
• the anti-spoofing clause on the c3-this-run exception ("never a config value, never model-supplied, never inferred from a drain/merge phrasing")
• the safety mechanism gating the C3 raise ("a fresh independent frontier-tier resolver")

C4/C5 unconditional-human-merge language is also preserved. This closes the gap the prior review flagged at the frontmatter (pre-invocation-decision) surface, and the skill body's full statement of the same contract is untouched.

Other checked surfaces: each plugin.json diff changes only the version field (author/permissions/MCP/hook config untouched); CHANGELOG.md entries are plain prose with no injected directives, script blocks, or executable content; no trigger phrases were dropped in any of the 9 other tightened descriptions (adhd/clarify, architecture/improve, claude-config/audit-instructions, docs-hygiene/audit-derivability, planning/audit-answers, session-flow/reconcile, session-flow/running-retro, discipline/reuse-or-replace, discipline/script-the-deterministic-work).

Conclusion: no security issues found. This PR has no security-relevant surface beyond the one prior finding, which is now resolved — it's a mechanical, additive-only doc trim with no logic, workflow, config, or authorization-boundary change.
· branch refactor/listing-budget-tighten

[claude]

Claude finished @kyle-sexton's task in 3m 25s —— View job

---

Review: PR #2054

• Gather context (diff vs origin/main, prior review threads, CLAUDE.md)
• Review each tightened SKILL.md description for trigger-phrase preservation, accuracy, and safety framing
• Check plugin.json version bumps + CHANGELOG entries for consistency
• Verify the fix commit (29babd4) addresses the prior babysit-loop finding
• Post findings

What I checked

Reviewed the 25 changed files (10 SKILL.md frontmatter trims, 8 plugin.json version bumps, 8 CHANGELOG.md entries) against CLAUDE.md's fresh-docs mandate (frontmatter description is a tracked contract surface) and the design rules for plugin skills.

Independently verified:

• plugins/source-control/skills/babysit-loop/SKILL.md's current description (fix commit 29babd4) contains 'autopilot', '--merge c3-this-run', and all six Use when: trigger phrases unchanged from the pre-PR original — the prior review's finding (dropped fail-closed default, tracked-seam-only invariant, anti-spoofing clause, independent-resolver detail) is fully addressed; all four are back in compact form and none of the trigger phrases regressed.
• Measured the restored description directly: 1,199 chars (grep -m1 '^description:' ... | cut -d'"' -f2 | wc -c), confirming kyle-sexton's fix-applied comment claim that it's "well under both the per-skill cap [1,536] and its pre-trim size [1,468]" is accurate.
• Spot-checked three other tightened descriptions (clarify, improve, audit-instructions) against their pre-PR originals — all are mechanical prose trims that keep every Use when:/Skip when: trigger phrase and the operative meaning intact; nothing else in this batch carries babysit-loop's authorization-boundary stakes (the other nine are report-only/read-only skills).
• All eight plugin.json diffs touch only the version field (spot-checked adhd; the earlier security-review pass checked the rest).
• CHANGELOG entries for the other 9 skills (clarify 766, improve 900, audit-instructions 948, script-the-deterministic-work/reuse-or-replace 872/836, audit-derivability 876, audit-answers 899, reconcile/running-retro) still match measured current file content — untouched since the original tighten commit.

Not independently verified (author-claimed): the pooled full-install listing-budget aggregate and check-skill.sh gate PASS results — I don't have those scripts' execution available in this lane; the security-review pass already flagged the same limitation.

Finding (inline)

Left one inline comment on plugins/source-control/CHANGELOG.md:10: the babysit-loop changelog entry's char-count claim (1,468 → 989 chars) predates the 29babd4 fix and is now stale — the description is actually 1,199 chars after the safety invariants were restored, a ~269-char saving rather than the ~479 the entry states. Minor/non-functional, but worth a quick correction since it's a claim about how much was trimmed off a merge-authority-relevant skill's description. The PR body's own summary table and per-plugin version-bump list have the same staleness (still show 931/537 saved and source-control 0.48.1, though plugin.json is already at 0.48.2) — those aren't tracked files so no inline anchor, but worth a pass before merge.

Everything else

Trigger-phrase preservation, scope (no unrelated files swept in), version/changelog hygiene elsewhere in the batch, and the babysit-loop safety-framing fix all check out.

[kyle-sexton]

Fixed: the changelog now states 1,468 → 1,197 (measured on the current file; net −271 after the invariant restoration). The PR-body table row for babysit-loop carries the same correction caveat — the post-change aggregate quoted there (85,650) was measured before the restoration commit, so the true current aggregate is ~85,858; still ~10.7x, conclusion unchanged.

[claude]

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

---

Security review

• Gather context (gh pr diff 2054, read all 25 changed files)
• Review changed SKILL.md / plugin.json / CHANGELOG.md files for security issues
• Post findings

Scope confirmed: 25 files — 10 one-line frontmatter description edits in SKILL.md files, 7 plugin.json diffs that touch only the version field, and 8 CHANGELOG.md prose additions. No .github/workflows files, hooks, MCP configs, permission grants, or scripts are touched, and no skill bodies are touched. This is a text-only trim of frontmatter listing descriptions toward a character budget.

Checks performed:

• Diffed every plugin.json hunk — each changes only the "version" string; description, author, permissions, and any MCP/hook config are untouched.
• Grepped the full diff for injection-adjacent patterns (<script, javascript:, eval(, exec(, curl, wget, etc.) — the only match is the literal skill name script-the-deterministic-work; no injected/executable content in any CHANGELOG.md addition.
• Re-checked plugins/source-control/skills/babysit-loop/SKILL.md, the one skill in this batch with real merge-authority semantics and the subject of an earlier review round's finding: the current description (post-fix commit 29babd4) retains all four safety-relevant qualifiers — the fail-closed default ("human-only until the target repo's tracked config adopts the lane"), the anti-widening invariant ("standing rung raises bind from the tracked config seam only"), the anti-spoofing clause on the c3-this-run exception ("never a config value, never model-supplied, never inferred from a drain/merge phrasing"), and the safety mechanism gating the C3 raise ("a fresh independent frontier-tier resolver"). C4/C5 unconditional-human-merge language is preserved too. No authorization-boundary regression.
• The other nine tightened descriptions (adhd/clarify, architecture/improve, claude-config/audit-instructions, docs-hygiene/audit-derivability, planning/audit-answers, session-flow/reconcile, session-flow/running-retro, discipline/reuse-or-replace, discipline/script-the-deterministic-work) are read-only auditors/correctors with no authorization or merge semantics — prose trims only, no safety-relevant content dropped.

Conclusion: no security issues found. This PR has no security-relevant surface — it's a mechanical, additive-only documentation trim with no logic, workflow, config, or authorization-boundary change. (Non-security note, out of scope for this review but visible in the diff: docs-hygiene's plugin.json still reads 0.9.6 while its CHANGELOG.md adds a [0.9.7] entry — a version-bump/changelog mismatch, not a security concern.)
· branch refactor/listing-budget-tighten

[claude]

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

---

Review: PR #2054 (re-review after synchronize)

• Gather context (diff vs origin/main, prior review threads, CLAUDE.md)
• Check whether the latest commit (16852ac) addresses the prior stale-CHANGELOG finding
• Review remaining changed files for correctness/maintainability
• Post findings

What changed since the last review

This synchronize added exactly one commit, 16852ac, touching only plugins/source-control/CHANGELOG.md (1 line). It corrects the babysit-loop entry's char-count claim from the stale 1,468 → 989 to 1,468 → 1,197, addressing the staleness finding from the prior review round (the entry previously predated fix commit 29babd4, which restored the four merge-authority safety invariants and grew the description back out).

Independently verified

• plugin.json for source-control is already at 0.48.2 (matches the ## [0.48.2] changelog heading — no further version bump needed for this docs-only correction).
• Measured the actual current babysit-loop description length directly: grep -m1 '^description:' plugins/source-control/skills/babysit-loop/SKILL.md | cut -d'"' -f2 | wc -c → 1,199 chars (1,200 including the trailing newline wc -c counts). The corrected changelog entry (1,197) is very close but not exact — left an inline nitpick on plugins/source-control/CHANGELOG.md:10 since this entry's whole purpose is precision about the trim amount (net saving is ~269 chars from 1,468, not 271). Non-functional, low severity.
• Confirmed no other file changed in this sync (git diff f395cf0..16852ac --stat shows only the one CHANGELOG line).

Everything else

All findings from the prior two review rounds — trigger-phrase preservation across all 10 tightened descriptions, the babysit-loop safety-invariant restoration in 29babd4, and version/changelog hygiene for the other 9 skills — still hold; nothing in this sync touched those.
· branch refactor/listing-budget-tighten

[kyle-sexton]

Measured both ways in the worktree: the description is 1,197 characters (python len) and 1,199 UTF-8 bytes (wc -c minus the newline — the em-dash costs 2 extra bytes). The suggested pipeline counts bytes; the changelog entry states chars, and 1,197 is the correct char figure consistent with the other nine entries (all measured as characters). No change made — resolving with this note as the record.