Repository navigation
docs(skills): trim non-load-bearing content from 7 skill descriptions - #507
Conversation
Adds the design doc and plan for the upcoming yellow-core skill description trim. Captures the diagnosis (61% of description budget concentrated in yellow-core's 17 skills, 5 verbose), the quality-driven audit criteria (no hard char cap, preserve WHAT + WHEN + differentiating clause), and the phase breakdown. Plan includes deepen-plan annotations covering the ~250-char auto-invocation threshold, body-content repetition mapping per skill, and empirical evidence that conservative trimming improves rather than degrades routing.
Trims 6 yellow-core skills + 1 yellow-council skill, cutting 2,066 chars total (56% reduction across modified skills). The cut content was enumerated trigger phrase lists, body-content repetition, and methodology bleed — none of which contributes signal at skill-selection time. WHAT clauses, WHEN triggers, and adjacent-skill differentiating clauses are all preserved. Char reductions: - compound-lifecycle: 686 → 220 (-68%) - ideation: 664 → 202 (-70%) - optimize: 613 → 234 (-62%) - debugging: 518 → 266 (-49%) - session-history: 516 → 242 (-53%) - agent-native-audit: 377 → 239 (-37%) - council-patterns: 285 → 190 (-33%) Why: Anthropic-documented evidence indicates descriptions over ~250 chars are in a degradation zone where trailing content is invisible to Claude's auto-invocation logic (anthropics/claude-code#44780). The 5 verbose yellow-core skills had trigger phrase lists and methodology details past that threshold — content that was both wasteful of listing budget and likely never read for routing decisions. Trimming brings them into the reliable auto-invocation window without losing selection signal. CONTRIBUTING.md "Skill Description Budget" section is updated to reconcile the existing "don't trim for budget" guidance with the new "trim non-load-bearing content for selection accuracy" principle. The two are compatible: don't cut signal to fit a budget, but do cut noise that adds no signal. Adjacent-pair distinguishability was verified for all 5 collision-risk pairs (ideation/brainstorming, agent-native-architecture/audit, memory-recall/remember-pattern, debugging/session-history, compound-lifecycle/knowledge-compounder). See plans/skill-description-audit.md and docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md for the full audit methodology, per-skill before/after analysis, and references.
|
User kinginyellow18@proton.me does not have a PR Review subscription. Go to Team management and add this email to the PR Review subscription. |
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (13)
📝 WalkthroughWalkthroughThis PR performs a skill-description audit: updates CONTRIBUTING.md trimming guidance, records audit plans and follow-ups, adds a changeset for the audit, and shortens YAML frontmatter ChangesSkill Description Audit
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
How to use the Graphite Merge QueueAdd the label graphite-queue to this PR to add it to the merge queue. You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request implements a quality-driven audit of skill descriptions to prevent truncation in Claude Code's auto-invocation logic, specifically targeting verbose descriptions in yellow-core and yellow-council. It updates CONTRIBUTING.md with new guidelines that distinguish between trimming for budget versus trimming for selection clarity, and adds comprehensive documentation including a brainstorm and an implementation plan. Feedback was provided to correct the name of an environment variable in the contribution guide to include the required prefix.
KingInYellow18
changed the title
ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one. |
Not up to standards ⛔🔴 Issues
|
| Category | Results |
|---|---|
| BestPractice | 1 minor |
| CodeStyle | 11 minor |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
There was a problem hiding this comment.
Pull request overview
Reduces verbosity in several SKILL.md description: frontmatter fields (selection metadata) to keep descriptions within a more reliable auto-invocation window while preserving WHAT + WHEN routing signal, and updates contributor guidance accordingly.
Changes:
- Trimmed 7 skill
description:fields (6 inyellow-core, 1 inyellow-council) to remove non-selection noise. - Updated CONTRIBUTING guidance to distinguish “trim for budget” from “trim for selection clarity.”
- Added planning/brainstorm artifacts plus a multi-plugin patch changeset.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/yellow-council/skills/council-patterns/SKILL.md | Shortens description while retaining authoring/usage trigger. |
| plugins/yellow-core/skills/session-history/SKILL.md | Shortens description; keeps “Use when…” trigger focused on prior-context recovery. |
| plugins/yellow-core/skills/optimize/SKILL.md | Removes methodology/judge-detail overflow from description; keeps rubric + measurable-goal intent. |
| plugins/yellow-core/skills/ideation/SKILL.md | Compresses description; preserves vague-problem trigger and brainstorm-orchestrator handoff. |
| plugins/yellow-core/skills/debugging/SKILL.md | Trims trigger phrase list; keeps causal-chain + hypothesis framing and “Use when…” triggers. |
| plugins/yellow-core/skills/compound-lifecycle/SKILL.md | Removes detailed ops enumeration from description; preserves docs/solutions sweep + knowledge-compounder hook. |
| plugins/yellow-core/skills/agent-native-audit/SKILL.md | Shortens description; keeps readiness/audit intent and orchestration-extraction trigger. |
| plans/skill-description-audit.md | Adds detailed audit plan and rationale for trimming descriptions. |
| docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md | Adds brainstorm capturing motivation and approach for description trimming. |
| CONTRIBUTING.md | Updates skill description guidance to emphasize selection clarity and truncation risk context. |
| .changeset/skill-description-audit.md | Declares patch bumps for yellow-core and yellow-council and explains the doc-only change. |
76267d7 to
cf484c2
Compare
|
User kinginyellow18@proton.me does not have a PR Review subscription. Go to Team management and add this email to the PR Review subscription. |
cf484c2 to
2b8881c
Compare
![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: 2b8881c366
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
…iption trims, plan move)
2b8881c to
650f3fc
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 650f3fc3c2
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.changeset/skill-description-audit.md:
- Around line 12-13: The changeset line "yellow-council skill (council-patterns
285→190). Total reduction: 2,186 chars (55% across modified skills)" is correct
but the PR summary mistakenly states "2,066 characters"; update the PR
description to match the correct total of 2,186 characters (and optionally
adjust any related aggregate totals) so the PR summary and the .changeset text
are consistent.
In `@CONTRIBUTING.md`:
- Line 432: Replace the incorrect environment variable name
CLAUDE_SLASH_COMMAND_TOOL_CHAR_BUDGET with the correct
SLASH_COMMAND_TOOL_CHAR_BUDGET in CONTRIBUTING.md (the occurrence at the
referenced location) so it matches the plan document and README; update the
single token text and verify any surrounding references or examples in the same
paragraph still read correctly after the rename.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5ad32429-0947-4757-89c8-2a16a0f84be2
📒 Files selected for processing (13)
.changeset/skill-description-audit.mdCONTRIBUTING.mddocs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.mdplans/complete/skill-description-audit-followups.mdplans/complete/skill-description-audit.mdplugins/yellow-core/skills/agent-native-architecture/SKILL.mdplugins/yellow-core/skills/agent-native-audit/SKILL.mdplugins/yellow-core/skills/compound-lifecycle/SKILL.mdplugins/yellow-core/skills/debugging/SKILL.mdplugins/yellow-core/skills/ideation/SKILL.mdplugins/yellow-core/skills/optimize/SKILL.mdplugins/yellow-core/skills/session-history/SKILL.mdplugins/yellow-council/skills/council-patterns/SKILL.md
650f3fc to
b35679f
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md (1)
201-223: ⚡ Quick winConsider documenting the resolution of open questions.
The three open questions listed here were part of the original brainstorm. Since line 4 indicates "Status: Implemented in PR
#507," consider appending a brief "Decisions Made" or "Resolution" section that closes each question with the actual decisions taken during implementation (or note which questions remain open/deferred). This would complete the retrospective documentation.Based on learnings from the follow-ups document, this was identified as task 3.4 in Phase 3.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md` around lines 201 - 223, Add a short "Decisions Made" or "Resolution" subsection after the "Open Questions" block that records the final outcome for each listed question (e.g., whether the config stayed user-level, whether the budget fraction was later lowered to 3% or deferred, and how third-party plugin descriptions were handled), reference the implementing PR number (`#507`) and note task 3.4 from Phase 3 where applicable, and mark any remaining open items as deferred; update the "Open Questions" section in docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md to include this closure so readers can see the final decisions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md`:
- Around line 201-223: Add a short "Decisions Made" or "Resolution" subsection
after the "Open Questions" block that records the final outcome for each listed
question (e.g., whether the config stayed user-level, whether the budget
fraction was later lowered to 3% or deferred, and how third-party plugin
descriptions were handled), reference the implementing PR number (`#507`) and note
task 3.4 from Phase 3 where applicable, and mark any remaining open items as
deferred; update the "Open Questions" section in
docs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md to include
this closure so readers can see the final decisions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0fc4405d-732a-4c79-afc6-d1f0fc06b94f
📒 Files selected for processing (8)
.changeset/skill-description-audit.mdCONTRIBUTING.mddocs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.mdplans/complete/skill-description-audit-followups.mdplans/complete/skill-description-audit.mdplugins/yellow-core/skills/agent-native-architecture/SKILL.mdplugins/yellow-core/skills/agent-native-audit/SKILL.mdplugins/yellow-core/skills/debugging/SKILL.md
✅ Files skipped from review due to trivial changes (4)
- plugins/yellow-core/skills/agent-native-architecture/SKILL.md
- plugins/yellow-core/skills/debugging/SKILL.md
- plugins/yellow-core/skills/agent-native-audit/SKILL.md
- CONTRIBUTING.md
b35679f to
c92432b
Compare
|
User kinginyellow18@proton.me does not have a PR Review subscription. Go to Team management and add this email to the PR Review subscription. |
c92432b to
35fd379
Compare
Merge activity
|
Summary
Trims 7 skill
description:frontmatter fields across yellow-core (6) andyellow-council (1), cutting 2,066 chars total (56% reduction) while
preserving WHAT + WHEN + adjacent-skill differentiating clauses.
The cut content is enumerated trigger phrase lists, body-content repetition
(methodology names, algorithm details), and capability listings the model
can extrapolate from a precise WHAT clause — none of which contributes
signal at skill-selection time.
Before/After
Why this is a quality fix, not a budget fix
CONTRIBUTING.md previously stated "Authors should not artificially trim
descriptions to fit the budget — that hurts auto-invocation accuracy"
(PR #459). That principle is preserved. This PR's premise is different:
Anthropic-documented evidence
(anthropics/claude-code#44780)
indicates descriptions over ~250 characters are in a degradation zone
where trailing content is invisible to Claude's auto-invocation logic. The
5 verbose yellow-core skills (500-690 chars) had trigger phrase lists and
methodology details well past that threshold — content that was both
wasteful of listing budget AND likely never read for routing decisions.
Trimming brings them inside the reliable auto-invocation window without
losing selection signal. CONTRIBUTING.md is updated to reconcile the two
principles (don't cut signal to fit a budget; do cut noise that adds no
signal).
What was preserved
ideation/brainstorming,agent-native-architecture/audit,memory-recall-pattern/memory-remember-pattern,debugging/session-history,compound-lifecycle/knowledge-compounderagent-native-architecture(load-bearingWHAT)
mcp-health-probe(load-bearing classification)
memory-remember-pattern(load-bearing differentiator)
What was NOT touched
patterns
description:frontmatter modified)validate-agent-authoring.js— no description-length validator added(out of scope per plan)
when_to_use:field adoption — separate refactorTest plan
grep -rEn '^description: [>|][-+]?$' plugins/*/skills/*/SKILL.mdreturns emptypnpm validate:schemaspasses (79 agents, 269 markdown files validated)pnpm typecheckcleanpnpm lintcleanpnpm test:unitpasses (3/3)Rollback observation
No automated test exists for skill-routing accuracy. If you observe
Claude routing differently to/from any of the 7 modified skills after
merge, comment on this PR or open an issue. The trim is reversible
via single-file revert + new patch changeset.
References
plans/skill-description-audit.mddocs/brainstorms/2026-05-09-claude-code-skill-bloat-brainstorm.md#44780,
#9716,
#56710,
plannotator#412
github.com/anthropics/skills
(target band: ~140-225 chars)
6d86b1d6)Summary by CodeRabbit
Documentation
Refactor
Greptile Summary
Trims
description:frontmatter across 8 SKILL.md files (7 yellow-core, 1 yellow-council) by removing trigger-phrase enumerations, methodology names, and body-content repetition that add no signal at skill-selection time, while preserving WHAT clauses, WHEN triggers, and adjacent-skill differentiators. CONTRIBUTING.md is updated to reconcile the prior "don't trim for budget" guidance with the new "trim non-load-bearing content for selection accuracy" principle.plans/complete/anddocs/brainstorms/as retrospective artifacts; a follow-up plan documents deferred clean-ups.Confidence Score: 5/5
All changes are frontmatter and markdown only — no skill body content, runtime logic, or schema definitions are modified.
Every SKILL.md edit is scoped to the single description: field; WHAT clauses, WHEN triggers, and adjacent-skill differentiators are preserved across all 8 modified files. The CONTRIBUTING.md rewrite is coherent and internally consistent.
CONTRIBUTING.md (env var name discrepancy noted in existing thread) and .changeset/skill-description-audit.md (skill count mismatch with PR title).
Important Files Changed
Flowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A[SKILL.md description] --> B{Char count?} B -->|under 200| C[Inspect only if obvious bloat] B -->|200-300| D[Inspect for redundancy] B -->|300-400| E[Read carefully for body-content bleed] B -->|over 400| F[Trim expected] D & E & F --> G{Cuttable patterns?} G -->|Trigger phrase enumeration| H[Cut] G -->|Body-content repetition| H G -->|Capability listing| H G -->|WHAT clause| I[Keep] G -->|Use-when trigger| I G -->|Differentiating clause vs adjacent skill| I G -->|Scope boundary preventing misfire| I H --> J[Draft trimmed description] I --> J J --> K{Adjacent-skill collision check} K -->|Distinguishable| L[Commit trim] K -->|Ambiguous| M[Restore differentiating clause] M --> JComments Outside Diff (1)
plans/complete/skill-description-audit-followups.md, line 453-500 (link)Both Phase 1.2 and Phase 2.1 are marked
[ ](pending) in this file, but both have already been implemented in this PR's diff:agent-native-audit: "Use when auditing for agent-native readiness, before adding a new agent capability, or when triaging agent-behavior regressions." The actualagent-native-audit/SKILL.mddiff in this PR ends with exactly that phrasing — the fix is already applied.agent-native-architecture. Theagent-native-architecture/SKILL.mddiff already drops exactly that clause.A reader of
plans/complete/skill-description-audit-followups.mdpost-merge will see two open[ ]items pointing to work that is already in HEAD, and may either re-apply the changes or be confused about what remains outstanding. Mark both items[x](or remove them) before committing this plan file.Prompt To Fix With AI
Prompt To Fix All With AI
Reviews (3): Last reviewed commit: "fix(docs): mark completed plans retrospe..." | Re-trigger Greptile