Fix ~2% skill usage: selective install (--only/--exclude) + skill-budget warning (v3.7.0)

[GopalGB]

Problem — "only ~2% of skills get used"

Per OpenAI's Codex Skills docs, Codex loads the initial skill list within only ~2% of the context window (~8,000 characters). With all 383 skills installed (descriptions total ~100 KB / ~25k tokens — ~12× over budget), Codex shortens descriptions and omits most skills from the auto-trigger list. They still run when invoked by path, but won't fire on their own — the "2% skill usage" symptom. Shipping 383 skills fundamentally exceeds this cap; the fix is to install a focused subset.

Fix

install.sh selective install (non-breaking — default still installs all):

• --only=<list> — install ONLY the listed packs/skills
• --exclude=<list> — install everything EXCEPT the listed packs/skills
• lists take comma-separated pack prefixes (e.g. xls) or exact skill names (e.g. production-audit)
• post-install warning above ~25 skills, printing the exact --only/--exclude/prune commands

bash install.sh --only=xls,pptx,pbi,production-audit,ponytail   # office subset (~20-25 fit the budget)
bash install.sh --exclude=ml,ai,sde,agentic,retail,research     # drop the heavy/eng packs

Docs: README gains a "⚠ Skill budget" callout; docs/OFFICE-SETUP.md gains office-subset guidance. Both point to /prompts:absorb for per-project scoping into ./.agents/skills/.

Verification

• --only=ponytail,production-audit → installs exactly those 2 (real install to temp dir confirmed).
• --only=xls,ponytail → 27; --exclude=ml,ai,sde,agentic,craft → 270 (verified: no prefix over-match; ml intentionally also matches the core ml-engineer).
• Default install → 383 + the budget warning fires.
• bash install.sh --help clean; bash -n install.sh OK; smoke 19/19 green.

Notes

• Follow-up to the merged Skill library overhaul: −career/algo, +ponytail +craft-* +agentic-* +production-audit +/prompts:setup (v3.6.1) #1 (branch restarted from main); this is a separate, new change.
• Alternative considered: shrinking every description to fit — rejected, since even a few packs blow the 8 KB budget; selective install is the real lever.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QTbNNSTfHHsQXrR1FgyK6t

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e671ff2b-1a6a-4615-80e1-d6878648621e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/tender-meitner-xbxa78

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}