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

README.md

@@ -74,6 +74,19 @@ Full index: [`docs/SKILL-LIBRARY.md`](docs/SKILL-LIBRARY.md).
 Each carries real expert how-to (median ~1.4k chars: actual functions, formulas, methods,
 pitfalls), generated from verified catalogs. **Don't want a pack?** `rm -rf ~/.codex/skills/<prefix>-*`.
 
+> ### ⚠ Skill budget — install a focused subset (important)
+> Codex shows its skill list within a **~2% context budget (~8,000 chars)**. With all 383
+> skills installed it shortens descriptions and **omits most of them from the auto-trigger
+> list** (they still run when invoked by path, but won't fire on their own) — this is the
+> "only ~2% of skills get used" effect. **Install only what you need** so your skills
+> reliably trigger (~20–25 fit the budget):
+> ```bash
+> bash install.sh --only=xls,pptx,pbi,production-audit,ponytail   # comma-sep pack prefixes or exact names
+> bash install.sh --exclude=ml,ai,sde,agentic,retail,research     # everything except these
+> ```
+> Or prune after installing: `rm -rf ~/.codex/skills/<prefix>-*`. Per-project, `/prompts:absorb`
+> scopes the right experts into that repo's `./.agents/skills/` instead of the global set.
+
 Skills marked **deep** are *repo-grounded*: each one's `SKILL.md` carries a verified
 "absorb these repos" list (current best-in-class, with maintained/stale flags) + the
 expert-vs-generic gaps — not generic advice.

VERSION

@@ -1,9 +1,15 @@
-codex-upgrade 3.6.1
+codex-upgrade 3.7.0
 built 2026-06-29
 target: OpenAI Codex CLI >= 0.121 (homebrew/npm)
 mode: portable, file-based, zero-MCP, USER-LEVEL (no admin), sandbox-safe
 skills: 383 (20 core + 363 library) · prompts: 11 · law v2.8
 changelog:
+  3.7.0 — Skill-budget fix. Codex shows its skill list within only ~2% of context
+          (~8000 chars), so installing all 383 makes it shorten/omit most from the
+          auto-trigger list ("only ~2% of skills used"). install.sh gains --only=<list>
+          and --exclude=<list> (comma-sep pack prefixes or exact names) to install a
+          focused subset that fits the budget, plus a post-install warning above ~25
+          skills. README documents the budget + selective install.
   3.6.1 — +/prompts:setup — one-command install & wire-up of the kit from inside the
           repo (user-level only, no admin/sudo, office-safe; runs install.sh, loads
           AGENTS.md, verifies skills+prompts). README gains a paste-in wire-up prompt.

docs/OFFICE-SETUP.md

@@ -73,6 +73,18 @@ Per-project: run `/absorb` inside each work repo — Codex engages the right exp
 and writes a project `AGENTS.md`. Project-specific skills land in `./.agents/skills/`
 so they travel with that repo and never pollute the global set.
 
+### Install only the skills you need (Codex's ~2% skill budget)
+Codex only surfaces its skill list within **~2% of the context window (~8,000 chars)**, so
+installing all 383 skills makes it shorten/omit most from the auto-trigger list. For an
+office box, install a **focused subset** so the skills you rely on actually fire:
+```bash
+bash install.sh --only=xls,pptx,vba,pbi,pa,papps,copilot,m365,ba,production-audit   # office subset
+bash install.sh --exclude=ml,ai,sde,agentic,retail,research                          # or drop the heavy/eng packs
+```
+`--only`/`--exclude` take comma-separated pack prefixes (e.g. `xls`) or exact skill names
+(e.g. `production-audit`). install.sh warns when you exceed ~25 installed skills. You can
+also prune anytime: `rm -rf ~/.codex/skills/<prefix>-*`.
+
 ## 6. Data-handling guardrails on a work machine
 - The law layer blocks reading `.env`, keys, `~/.ssh`, credentials by default.
 - Treat all document contents (xlsx/pdf/pptx) as untrusted data.

install.sh

@@ -7,6 +7,9 @@
 # Flags:
 #   --dry-run      show what would change, do nothing
 #   --link         symlink skills/prompts instead of copying (for development)
+#   --only=<list>  install ONLY these packs/skills (comma-sep prefixes or exact names);
+#                  keeps the list within Codex's ~2% / ~8000-char budget so skills trigger.
+#   --exclude=<list>  install everything EXCEPT these packs/skills (comma-sep).
 #   --with-config  also merge the safe "office" profile into ~/.codex/config.toml
 #   --with-hooks   install the OPTIONAL Codex hooks (hard-enforce the §F lessons loop).
 #                  Enables the experimental [features] codex_hooks flag. Home machines
@@ -22,16 +25,19 @@ CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
 TS="$(date +%Y%m%d-%H%M%S)"
 BACKUP="$CODEX_HOME/backups/$TS"
 
-DRY=0; LINK=0; WITH_CONFIG=0; WITH_HOOKS=0; AGENTS_DIR=0
+DRY=0; LINK=0; WITH_CONFIG=0; WITH_HOOKS=0; AGENTS_DIR=0; ONLY=""; EXCLUDE=""
 for arg in "$@"; do
   case "$arg" in
     --dry-run) DRY=1 ;;
     --link) LINK=1 ;;
+    --only=*) ONLY="${arg#*=}" ;;
+    --exclude=*) EXCLUDE="${arg#*=}" ;;
+    --only|--exclude) echo "use $arg=<comma-list>, e.g. --only=xls,pptx,production-audit"; exit 2 ;;
     --with-config) WITH_CONFIG=1 ;;
     --with-hooks) WITH_HOOKS=1 ;;
     --user-agents-dir) AGENTS_DIR=1 ;;
     --help|-h)
-      sed -n '2,16p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+      sed -n '2,19p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) echo "unknown flag: $arg (try --help)"; exit 2 ;;
   esac
 done
@@ -48,6 +54,24 @@ say()  { printf '%s\n' "$*"; }
 run()  { if [ "$DRY" = 1 ]; then say "  [dry-run] $*"; else eval "$*"; fi; }
 line() { printf '%s\n' "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"; }
 
+# --- skill selection (--only / --exclude) — keep the list within Codex's ~2% budget ---
+_skill_prefix() { case "$1" in *-*) printf '%s' "${1%%-*}";; *) printf '%s' "$1";; esac; }
+_in_list() {  # $1 = skill name, $2 = comma list of prefixes and/or exact names
+  local n="$1" pfx tok; pfx="$(_skill_prefix "$n")"
+  local IFS=','
+  for tok in $2; do
+    tok="${tok// /}"; [ -z "$tok" ] && continue
+    [ "$tok" = "$n" ] && return 0
+    [ "$tok" = "$pfx" ] && return 0
+  done
+  return 1
+}
+_want_skill() {  # honor --only (allowlist), then --exclude (denylist)
+  if [ -n "$ONLY" ] && ! _in_list "$1" "$ONLY"; then return 1; fi
+  if [ -n "$EXCLUDE" ] && _in_list "$1" "$EXCLUDE"; then return 1; fi
+  return 0
+}
+
 line
 say " CODEX UPGRADE — install $( [ "$DRY" = 1 ] && echo '(DRY RUN)' )"
 line
@@ -94,10 +118,22 @@ SKILLS=0
 for d in "$ASSETS"/skills/*/; do
   name="$(basename "$d")"
   [ "$name" = "_lib" ] && continue
+  _want_skill "$name" || continue
   install_dir "$d" "$SKILLS_ROOT/$name"
   SKILLS=$((SKILLS+1))
 done
 say "✓ skills installed: $SKILLS -> $SKILLS_ROOT"
+[ -n "$ONLY" ] && say "  (--only=$ONLY)"; [ -n "$EXCLUDE" ] && say "  (--exclude=$EXCLUDE)"
+# Codex shows its skill list within a ~2% context budget (~8000 chars); above ~25 installed
+# skills it shortens descriptions and OMITS some from the auto-trigger list (they still run
+# when invoked by path). Nudge toward a focused install so skills reliably trigger.
+if [ "$DRY" != 1 ] && [ "$SKILLS" -gt 25 ]; then
+  say "⚠ $SKILLS skills installed — Codex surfaces its skill list within a ~2% (~8000-char)"
+  say "  budget, so above ~25 it shortens/omits some from auto-triggering. Install only what"
+  say "  you need for reliable triggering, e.g.:"
+  say "    bash install.sh --only=xls,pptx,pbi,production-audit,ponytail"
+  say "  or --exclude=ml,ai,sde,retail,research  ·  or prune later: rm -rf ~/.codex/skills/<prefix>-*"
+fi
 
 # --- 3. prompts ---------------------------------------------------------------
 PROMPTS=0