perf(skills): trim the remaining listed descriptions over 500 in #4661 plugins

[kyle-sexton]

Closes #4661

Summary

Eight listed skill descriptions in plugins the issue names were still over 500 characters on origin/main (description plus when_to_use, whitespace-normalised, YAML-parsed). This PR trims them, so no listed skill in the issue's 18 plugins is over 500. The prior drain PR (#5422) covered architecture and improvement:find; the native-route sweeps (#5556, #5570) then re-grew several descriptions by prepending a When the bundled <x> skill resolves ... prefer ... clause.

Fix

Frontmatter only. Each skill keeps its native-route phrase in shortened form, its quoted trigger phrases and its sibling boundary. No rename, merge or disable-model-invocation change, no plugin.json description change.

Skill	Before	After
claude-config:audit-instructions	838	494
claude-config:audit-permission-state	677	497
claude-config:audit	623	474
context-budget:audit	767	439
claude-ops:observability	721	456
claude-ops:inventory	522	464
code-tidying:audit-dead-code	501	439
fleet:reach	1112	475

Patch bumps with a CHANGELOG entry: claude-config 0.55.1, claude-ops 0.77.3, context-budget 0.6.48, code-tidying 0.25.3, fleet 0.2.1.

Verification

• check-listing-budget.sh plugins/*/skills aggregate: 131638 chars before (origin/main), 129613 after.
• Measured by YAML parse over the issue's 18 plugins: 8 skills over 500 on origin/main, 0 on this branch.
• check-changelog-parity.sh --check, --check-bump origin/main and --check-order: pass.
• validate-plugins.sh: pass. validate-plugin-contracts.mjs: pass (59 setup skills, 4976 files).
• check-changed-skills.sh origin/main: 8 skills checked, 0 failed.
• check-purged-em-dashes.sh --check: no em dashes. markdownlint-cli2 on 13 changed files: 0 issues.
• affected-tests.sh: no suites selected (every changed file is a no-suite class).
• Diff against origin/main shows only modified files and no name: or disable-model-invocation change.

Related

• perf(skills): finish cutting the shared skill-listing cost after #4555 #4657 (parent), perf(skills): trim architecture, improvement, claude-config, discipline descriptions under 500 chars #5422 (earlier trims), docs: remove agent-encoded decisions and correct decision records #5288 (deleted the cap-exceptions doc), feat(claude-ops): bake the explain-usage route phrase into observability's description #5556 and feat(plugins): bake native route phrases into the remaining sweep units #5570 (native-route phrases kept here), feat(claude-config): derive more audit criteria from docs and the binary #5561 (edits the claude-config:audit body, not its frontmatter).
• Not covered here: listed skills over 500 in plugins the issue does not name. On this branch that is 82 skills across adhd, ai-slop, animation, attribution, bugs, claude-memory, codebase-health, computer-use, context7, coupling, debugging, disk-hygiene, domain-driven-design, education, evals, event-storming, firecrawl, gaming, github, kindle-dedrm, machine-health, mcp-tools, mutation-testing, naming, pixel-art, playbooks, playgrounds, playwright, plugin-quality, prototype, repo-fleet-hygiene, repo-hygiene, review, skill-quality, songwriting, source-control, tdd, testing, toolchain, verification, visualization, wizard, writing and x. This PR does not trim them.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-30T21:58:26.976330Z	9e4e277	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

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

---

Review: perf(skills): trim remaining listed descriptions over 500 (#5629)

• Gather context (gh pr diff 5629, read all 18 changed files)
• Understand request: CI code-review lane, correctness/maintainability only
• Skip gate: not applicable, PR is open and has real review surface
• Review changed frontmatter/CHANGELOG/plugin.json files
• Independently spot-check the PR's own character-count claims

Summary

Mechanical frontmatter-only trim across 5 plugins (claude-config, claude-ops, code-tidying, context-budget, fleet). I verified plugin.json versions match their CHANGELOG.md headers (0.55.1 / 0.77.2 / 0.25.3 / 0.6.48 / 0.2.1 — all consistent), and that every referenced sibling/bundled skill name (audit-prompting-postures, audit-permission-grants, session-flow:continue-in-background, repo-fleet-hygiene, etc.) still exists. The code-tidying:audit-dead-code description drops the "Orphaned files: listed source extensions and shebang scripts" clause, but that detail is preserved in the skill body (SKILL.md#L36), so it's not a real information loss.

fleet:reach's removal of the standalone when_to_use frontmatter field (folding its content into description) is consistent with how Claude Code actually uses it — plugins/playbooks/skills/skill-authoring/reference/authoring-guidance.md confirms when_to_use is just appended to description in the skill listing, so merging them is a legitimate way to cut the aggregate length without a functional change.

Note (non-blocking, not anchorable to a changed line)

I independently re-measured the description character counts the PR body's before/after table reports (extracting each file's frontmatter description: value and counting bytes). Seven of eight match the table exactly. One does not:

• context-budget:audit: table claims 462 after, but the committed description (plugins/context-budget/skills/audit/SKILL.md#L2) measures 439 characters. The "before" value (767) in the same row does match the prior origin/main content, so this isn't a table-row misalignment, just one wrong cell.

This doesn't affect correctness — 439 is still comfortably under the 500-char budget the PR is enforcing, so the actual result is better than claimed, not worse. Flagging only because the PR body asserts this as independently measured verification; the row is off, though the change itself is fine.

No blocking findings. The diff is frontmatter-only as claimed (no name: or disable-model-invocation changes), and the plugin.json/CHANGELOG.md pairs are internally consistent.
· branch

[claude]

Claude finished @kyle-sexton's task in 46s —— View job

---

Security review complete

• Gather context (PR perf(skills): trim the remaining listed descriptions over 500 in #4661 plugins #5629, HEAD 9e4e277)
• Fetch PR diff and read changed files
• Apply skip gate / security criteria from /review:security-review
• Post findings

No security issues found.

This PR only trims description/when_to_use frontmatter strings (and merges fleet:reach's when_to_use into its description) on 8 SKILL.md files to fit the 500-character listing budget, plus the matching plugin.json version bumps and CHANGELOG.md entries. All hunks are confined to the YAML frontmatter block above each skill's body; no skill body, script, hook, or logic changed.

Checked specifically for the instruction-surface-deletion case this lane watches for (a trimmed instruction silently dropping a guardrail): none of the removed text matches a Gate 0 protected class (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority) per docs/conventions/instruction-exception-register/README.md. What was trimmed is redundant trigger-phrase examples and routing prose — sibling "Not for:" boundaries, native-route preference phrases, and quoted triggers are all explicitly preserved (and the PR body documents this), so no security- or safety-relevant behavior narrows as a result.

No injection surfaces, secrets handling, auth/access-control logic, or Actions workflow changes are present in this diff.

[claude]

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

---

Review: perf(skills): trim remaining listed descriptions over 500 (#5629)

• Gather context (gh pr diff 5629, read all 8 changed SKILL.md files plus the 5 plugin.json/CHANGELOG.md pairs)
• Run the /review:code-review skip gate — PR is open, not a draft, and HEAD (a7891b3) has changed since this lane's last review of 9e4e277, so a fresh pass applies
• Review frontmatter/CHANGELOG/plugin.json changes for correctness
• Post findings

Summary

Mechanical frontmatter-only trim, as claimed: every hunk is confined to description/when_to_use lines in 8 SKILL.md files plus the matching plugin.json version bump and CHANGELOG.md entry in 5 plugins. I re-checked each plugin's plugin.json version against its CHANGELOG.md heading and they're internally consistent (claude-config 0.55.1, claude-ops 0.77.3, code-tidying 0.25.3, context-budget 0.6.48, fleet 0.2.1). All frontmatter YAML remains well-formed, and fleet:reach's merge of when_to_use into description matches how Claude Code actually renders the listing (confirmed against plugins/playbooks/skills/skill-authoring/reference/authoring-guidance.md:29, which says when_to_use is appended to description).

One inline finding below on fleet:reach.

Non-blocking, PR body only (no changed line to anchor): the body's "Patch bumps" list gives two stale version numbers. It says claude-config bumped to 0.54.1 and claude-ops to 0.77.2, but the actual diff bumps them to 0.55.1 (plugin.json#L4) and 0.77.3 (plugin.json#L4) respectively — the committed files and their CHANGELOG.md headings already agree with each other, so this is purely a stale PR description, not a code defect.

Not independently re-verified: the PR's per-skill before/after character counts (check-listing-budget.sh and a YAML parse are the author's claimed methodology). This sandbox's Bash tool didn't allow running that script or any ad hoc script to recompute them, so I'm not restating those numbers as independently confirmed either way.
· branch

[claude]

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

---

/review:security-review — complete

• Gather context (PR perf(skills): trim the remaining listed descriptions over 500 in #4661 plugins #5629, HEAD a7891b3)
• Fetch PR diff and read changed files (gh pr diff 5629)
• Apply skip gate / security criteria
• Check instruction-surface deletions against protected classes
• Post findings

No security issues found.

This PR only trims description/when_to_use frontmatter strings across 8 SKILL.md files (5 plugins: claude-config, claude-ops, code-tidying, context-budget, fleet) to fit the 500-character listing budget, plus the matching plugin.json version bumps and CHANGELOG.md entries. Every hunk is confined to the YAML frontmatter block above each skill's body (or to version/changelog text); no skill body, script, hook, or logic changed. No injection surfaces, secrets handling, auth/access-control logic, or Actions workflow changes are present.

Instruction-surface check. I read docs/conventions/instruction-exception-register/README.md and walked every trimmed description against the protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority):

• What's removed in each case is redundant trigger-phrase examples, duplicate wording, and routing prose (e.g. claude-config:audit-instructions drops 'instruction audit', 'are my instructions holding the model back', 'instruction re-reads CLAUDE.md', 'conflicting instructions' as quoted triggers, keeping the rest).
• Every skill's "Not for:" sibling boundary, native-route preference phrase, disallowed-tools, and disable-model-invocation line is unchanged in this diff — none of those enforcement surfaces narrowed.
• fleet:reach folds its standalone when_to_use field into description (Claude Code appends when_to_use to description for the listing anyway, so this is a non-functional merge) and trims the prose mentioning "the permission posture" — but the actual permission posture logic lives in the skill body, not this description line, so nothing that enforces behavior is removed, only a line that referenced it.
• code-tidying:audit-dead-code drops "Orphaned files: listed source extensions and shebang scripts" from the description; that's scope-clarifying prose still present in the skill body, not a guardrail.

No removed clause matches a protected class — nothing that gated an irreversible action, secret handling, data integrity, external publication, legal compliance, or agent authority decision was touched. This confirms the two automated review passes already posted on this PR (Claude code-review and Claude security-review runs, and the Codex review) found the same: frontmatter-only, no functional or security-relevant change.

branch

[claude]

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

---

Review: perf(skills): trim remaining listed descriptions over 500 (#5629)

• Gather context (gh pr diff 5629, read all 18 changed files)
• Run skip gate — PR is open, not draft; HEAD (f789223) has a new commit since this lane's last review of a7891b3, so a fresh pass applies
• Review changed frontmatter/CHANGELOG/plugin.json files
• Independently re-measure the 8 trimmed descriptions
• Post findings

Summary

Mechanical frontmatter-only trim across 5 plugins (claude-config, claude-ops, code-tidying, context-budget, fleet), confirmed by diffing each commit in gh pr diff 5629 --patch: every hunk is confined to a description/when_to_use line, a plugin.json version bump, or a CHANGELOG.md entry. No name:, disable-model-invocation, or skill-body change.

I was able to run wc -c in this sandbox (earlier passes on this PR reported the sandbox refused script execution), so I independently re-measured all 8 trimmed description fields directly from the committed files rather than restating the PR body's own claimed counts. None of the 8 carries a separate when_to_use field anymore (confirmed via grep -l when_to_use across all 8 — no matches), so description alone is the full budgeted string for each:

Skill	Measured	Table claims
claude-config:audit-instructions	494	494 ✓
claude-config:audit-permission-state	497	497 ✓
claude-config:audit	474	474 ✓
context-budget:audit	439	439 ✓
claude-ops:observability	456	456 ✓
claude-ops:inventory	464	464 ✓
code-tidying:audit-dead-code	439	439 ✓
fleet:reach	490	475 ✗ (stale, see below)

All 8 are comfortably under the 500-char budget. I also confirmed plugin.json/CHANGELOG.md heading pairs are internally consistent on this HEAD: claude-config 0.55.1, claude-ops 0.77.3, code-tidying 0.25.3, context-budget 0.6.48, fleet 0.2.1 (note these differ from the PR body's "Patch bumps" list, which still names the pre-rebase 0.54.1/0.77.2 — origin/main advanced under this branch since that text was written; a prior review pass already flagged this same class of staleness on an earlier HEAD).

fleet:reach's inline review thread (dropping "start a session" from the description) is resolved as of the latest commit: the description now reads ...to run, prompt, query, message or start a session, with no human copying prompts. (plugins/fleet/skills/reach/SKILL.md#L2), measured at 490 chars.

Non-blocking note (PR body only, no changed line to anchor)

The PR body's before/after table still lists fleet:reach "After" as 475, which was correct for the commit the table was written against but is now stale: the latest commit (f789223, restoring "start a session" per the review thread) brings it to 490, which I measured directly above. Still well under the 500 budget, so this doesn't affect correctness — flagging only because the table is presented as verification data, and it's now one commit behind the code it describes.

No blocking findings

Diff is frontmatter-only as claimed. No security-relevant, instruction-surface, or logic change (consistent with the two security-review passes already posted on this PR).
· branch

[claude]

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

---

/review:security-review — complete

• Gather context (PR perf(skills): trim the remaining listed descriptions over 500 in #4661 plugins #5629, HEAD f789223)
• Fetch PR diff (gh pr diff 5629) and read changed files
• Apply skip gate / security criteria
• Check the new commit against the instruction-surface-deletion lens
• Post findings

No security issues found.

This review covers the full PR diff (5 plugins, 18 files: plugin.json version bumps, CHANGELOG.md entries, and 8 SKILL.md frontmatter trims). All of it was already clean on the two prior passes at a7891b3; the only change since then is HEAD commit f789223, which touches a single line: plugins/fleet/skills/reach/SKILL.md#L2.

That commit is the author's direct response to the earlier inline finding on this PR (start a session had dropped out of the routing description). It's a pure addition — restoring or start a session to the verb list — not a removal, so it doesn't fall under the instruction-surface-deletion lens at all: nothing is narrowed or softened, a capability that had silently dropped out of the model-facing routing text is put back. I re-read docs/conventions/instruction-exception-register/README.md (present in this checkout) and re-walked the description against its protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority) as before: unchanged conclusion, nothing in this field enforces any of those classes, and the "Not for:" sibling boundary, disable-model-invocation, and argument-hint lines are all untouched by this commit.

No injection surfaces, secrets handling, auth/access-control logic, or Actions workflow changes are present anywhere in this diff. This confirms the two Claude security-review passes and the Codex review already posted on this PR: frontmatter-only, no functional or security-relevant change.
· branch