feat(claude-ops): audit-skill-visibility names misconfigured skills, longest descriptions, and next actions - #4107
Conversation
…longest descriptions, and next actions The Markdown report counted misconfigured skills without naming them, printed an overflow figure without showing which descriptions spend the budget, and ended with no pointer to what to do. All three fields already sat in the JSON model, so the renderer now tables them: misconfigured skills with their cause and one remedy per cause under Reachability; the ten longest competing descriptions with character counts under Listing budget whenever a row overflows, labelled as description length and never as a starvation ranking so an unscored run renders it unchanged; and a closing Next actions section built only from the conditions present. Every table caps at ten rows and counts the rest. The JSON is unchanged. Release claude-ops 0.52.0. Closes #4105 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013GSKHZcGv3r3p6gpc8N8ai
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 1m 35s —— View job Code review complete
SummaryReviewed the diff ( No blocking findings. The change is a clean, behavior-preserving extraction plus three new render helpers:
I could not independently execute No inline comments posted — no findings met the high-signal bar (a careful reviewer would block or flag). |
|
Claude finished @kyle-sexton's task in 1m 2s —— View job Security review —
|
|
Last security-reviewed head: |
|
Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5459a1e162
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…t actions at the effective budget control Three review findings on the new render tables. The length table ranked on the capped charge, so every description over skillListingMaxDescChars tied at the cap and sorted by name; each listing row now also carries the uncapped description_chars, the table ranks on it with the charge shown beside it, and the caption says trimming lowers the overflow only under the cap. The next-actions line always recommended raising the fraction, which cannot move the overflow when SLASH_COMMAND_TOOL_CHAR_BUDGET overrides it, when a --budget-fraction pin changed only the report, or when managed policy supplied it; it now names the control the provenance says is effective. The misconfigured caption claimed a skill could never match, which is true of malformed frontmatter and false of a missing description, since the product falls back to the first body paragraph; it now states both. JSON schema 1.2.0, additive. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013GSKHZcGv3r3p6gpc8N8ai
…sibility-hxhyma # Conflicts: # plugins/claude-ops/CHANGELOG.md
…n prose across 36 skills (#4108) No related issue: this closes the one decision the audit behind #4072 reclassified to a human, resolved by re-reading the sources; no issue tracks it. ## Summary Anthropic's [skill-authoring best-practices page](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions) rules out first and second person in a skill description. Its two Avoid examples are "I can help you process Excel files" and "You can use this to process Excel files", and its reason is that the text is injected into the system prompt. Its own effective examples, the Claude Code skills page's examples, and the bundled skill-creator's frontmatter are all imperative ("Extract text and tables from PDF files", "Fix a GitHub issue", "Create new skills..."), so imperative and third-person singular both conform and this marketplace's imperative descriptions are not a deviation. The real gap was description prose that addresses the reader. A scripted scan that strips quoted trigger phrases and hyphenated or slash-joined identifiers found it in 36 skills across 24 plugins. ## Fix - **36 skill descriptions** (adhd, bugs, claude-config, claude-ops, code-metrics, discipline, discovery, docs-hygiene, education, firecrawl, improvement, instruction-placement, kindle-dedrm, mutation-testing, overengineering, playgrounds, plugin-quality, prototype, session-flow, songwriting, source-control, tdd): each clause that addressed the reader now names the user, the session, the assistant, or the repository. Examples: "so you can act on it" becomes "so the reader can act on it"; "a permission rule you cannot locate" becomes "a permission rule whose source is unknown"; "books you own" becomes "books the user owns"; "synthesize where we stand" becomes "synthesize where the session stands". Quoted trigger phrases (user utterances such as 'audit my .claude folder'), backticked tokens, slash tokens, and skill names are byte-identical. No description grew by more than 20 codepoints or crossed 1,024; two that sat near the cap got shorter. - **One clause stays as it was.** The native-surface presence gate ("resolves in your session") in the two claude-ops descriptions (`audit-install-state`, `audit-skill-visibility`) is a literal token the native-overlap registry self-check matches against every baked store row, so `validate-plugins.sh` fails when it is reworded (that is what turned `7cbf30ab8` red). Commit `af0e7b274` restores the token in both and the claude-ops changelog entry says why. Changing the token itself touches the checker, its tests, twelve skills, the seam-phrasing convention, and the store evidence, and is tracked as #4112. - **Two plugin manifests** (kindle-dedrm, session-flow) carried the same wording in their own descriptions and follow; `docs/CATALOG.md` regenerated. - **playbooks 0.11.2**: `skill-authoring/reference/authoring-guidance.md` states the rule as the page defines it, with the Avoid examples, the system-prompt reason, and the finding that imperative conforms, and its Record cites the three imperative example surfaces with a recheck trigger for the page rewriting its examples. `reference/authoring-checklist.md` gains the matching judgment row. The previous text called the fleet's imperative voice a deviation to leave alone, which the sources do not support. - Each of the 24 touched plugins gets a patch bump and a CHANGELOG entry naming its rewritten skills. Main moved four times while this was open; the merge commits `2cc1102c0`, `f082ed2f8`, `7cbf30ab8`, and `0b10ccae7` restack this change's entries above the newer main entries: claude-ops to 0.54.1 (above #4099, #4107, and #4092), code-metrics to 0.2.3 (above #4098), source-control to 0.55.76 (above #4106). Every other plugin's bump is unchanged. ## Verification Run on Linux at head `0b10ccae7`: - Voice scan over all 258 skill descriptions (quoted phrases and identifiers stripped, then first and second person pronouns matched): 36 hits before; after, only the two claude-ops descriptions that carry the checked gate token (3 occurrences of that token, nothing else). An uppercase variant scan finds 0. - `scripts/validate-plugins.sh`: passes; the native-overlap self-check reports degraded (stale-but-honest advisories, the same as main), not broken. - `scripts/check-changed-skills.sh origin/main`: 35 skills checked, 0 failed, no dropped-trigger-keyword WARN on any skill (check 3 compares every trigger phrase against the base ref). - `check-changelog-parity.sh --check`, `--check-bump origin/main`, `--check-order`: pass across all 93 changelogs. `generate-catalog.mjs --check`: in sync. - `markdownlint-cli2` over every changed markdown file: 0 issues. `typos` over the added lines: clean. `check-purged-em-dashes.sh`: no em dashes. - Diff shape: 36 SKILL.md files touched on their description line only, 23 plugin.json version bumps plus the two manifest description edits, 23 CHANGELOG.md entries, the two playbooks spokes, and the catalog. No skill body, script, or test changed. - `scripts/affected-tests.sh --run`: no suites selected (every changed file is a recorded no-suite class). - CI: `ci-status` and every lane green on `45af55489` (draft) and on `2cc1102c0` (draft and after the ready flip). Codex review on `2cc1102c0`: completed, no findings. `7cbf30ab8` went red on `test-linux` (the gate-token self-check above); `af0e7b274` carries the fix and `0b10ccae7` merges the latest main on top. ## Related - Follow-up to #4069 and #4072. The two fresh-context validators behind #4072 both reclassified the description-voice row to a human decision on the premise that imperative and third person are two voices; re-reading the page's examples shows they are one conforming class, so the decision resolves on evidence rather than taste. The reasoning and the scan live in the untracked `.work/skill-authoring-best-practices/INTERVIEW-ACCEPTED.md` ("Audit resolution", row I1.2) of the authoring checkout. - #4112 tracks retokening the presence gate so the last two descriptions lose their second person too. - #4070 and #4071 remain the deferred follow-ups from #4069. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01MSGD4WGhUXepHq3LTmpQML --------- Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Closes #4105
Summary
The
claude-ops:audit-skill-visibilityMarkdown report counted misconfigured skills without naming them, printed an overflow figure without showing which descriptions spend the budget, and ended with no pointer to what to do. Every field the tables need already sat in the JSON model. This is the last item from the session that scoped and fixed #4076, #4077 and #4078: it was agreed there and never filed.Fix
skillListingMaxDescCharsand would order every over-cap description by name. Labelled as length and never as a starvation ranking, so an unscored run renders it unchanged and still withholds which skills lose theirs.SLASH_COMMAND_TOOL_CHAR_BUDGETwhen it overrides the fraction, the managed policy file when it supplied the fraction, otherwise the settings file that did; a--budget-fractionpin is called out as changing the report only.listing_overflowspredicate is factored out ofstarvation_withheldand shared.description_chars(uncapped source length) beside the cappeddemand_chars.plugins/claude-ops-> 0.53.0 with a CHANGELOG entry (0.52.0 was taken by feat(claude-ops): audit-performance projects hook fan-out per tool and file kind #4099 on main while this PR was in review); one paragraph added to SKILL.md's "Reading the output".Verification
python3 -m unittest test_audit_skill_visibility: 148 tests, OK (140 -> 146 -> 148; newRenderTablesTestcovers cause and per-cause remedy, the ten-row cap, no length table when the listing fits, source-length order above the cap with the charge shown, nolikely-starvedwording when unscored, the past-ten count, next actions naming only present conditions, and the effective budget control for the env override, a pin, a settings file, and managed policy).scripts/run-ruff.sh checkandformat --check: clean.markdownlint-cli2on SKILL.md and CHANGELOG.md: clean.scripts/check-changelog-parity.sh --check,--check-bump origin/main,--check-preserved origin/main: clean on the merged tree.check-purged-em-dashes.sh: no em dashes.scripts/affected-tests.sh --runon the merged tree: four shell suites PASS (both audit-skill-visibility suites plus the two selected by the merged audit-performance change); the Python lane is a NOT RUN ecosystem by design and was run directly.SLASH_COMMAND_TOOL_CHAR_BUDGETexported it names the env override instead; at 1M/4 no length table renders and the line reads "Nothing to fix from this run."Related
🤖 Generated with Claude Code
https://claude.ai/code/session_013GSKHZcGv3r3p6gpc8N8ai