@olegkoval/agent-skills 1.12.0 → 1.14.0

package/packages/software-development/skill-budget-audit/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: skill-budget-audit
+description: Diagnose and fix Claude Code's skill context budget overflow — identify heavy plugin bundles that exceed the 2% budget, remove domain-specific ones, deactivate rarely-used skill sets, and validate the warning clears. Use when Claude Code shows "Exceeded skills context budget" or skill descriptions are stripped.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Claude Code only. Requires access to ~/.claude/ and ~/.claude/plugins/
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - claude-code
+    - skills
+    - plugins
+    - context-budget
+    - token-economy
+    - performance
+---
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · Skill context budget overflow appeared in 2 sessions this week (Jun 2026): initial investigation (7 turns, 742 skills hidden) and cleanup followup (14 turns)*
+
+# Skill Context Budget Audit
+
+## Overview
+
+Claude Code allocates 2% of its context window for skill descriptions. With too many plugins installed, descriptions get stripped and skills become invisible. This skill audits plugin bundles, removes unused domain-specific ones, and restores skill discoverability.
+
+## When to Use
+
+- Claude Code shows: `⚠ Exceeded skills context budget of 2%. All skill descriptions were removed and N additional skills hidden.`
+- Skill invocations fail silently or Claude cannot find a skill by name
+- After installing multiple plugin bundles, noticing slowdown or skill lookup failures
+- Periodically as a maintenance step when adding new skill collections
+
+## Workflow
+
+### 1. Confirm the Symptom
+
+```bash
+# Check Claude Code logs for context budget warning
+cat ~/.claude/logs/claude-code.log 2>/dev/null | grep -i "skill" | tail -20
+
+# Or count installed plugins
+ls ~/.claude/plugins/cache/ | wc -l
+```
+
+If you see `Exceeded skills context budget` or more than ~20 plugin bundles, proceed.
+
+### 2. Inventory Installed Plugins
+
+```bash
+# List all installed plugins with size
+du -sh ~/.claude/plugins/cache/*/ 2>/dev/null | sort -rh | head -30
+
+# Count skills per bundle
+for dir in ~/.claude/plugins/cache/*/; do
+  count=$(find "$dir" -name "*.md" -path "*/skills/*" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$count  $dir"
+done | sort -rn | head -20
+```
+
+### 3. Identify Removal Candidates
+
+Remove bundles that match any of these criteria:
+
+| Criterion | Example bundles |
+|-----------|----------------|
+| Domain not active in current projects | `claude-for-financial-services`, `bitwize-music` |
+| Duplicate superpowers installations | Multiple `superpowers-*` versions |
+| Language-specific bundles for inactive languages | `cc-skills-golang` when not working in Go |
+| Bundles with 30+ skills you never invoke | Large catch-all collections |
+
+Keep: core workflow skills (superpowers, agent-skills), project-specific skills, personal skill collections.
+
+### 4. Remove Heavy Bundles
+
+```bash
+# List Claude Code plugins (check settings.json for registered ones)
+cat ~/.claude/settings.json | grep -A 50 '"plugins"'
+# or
+cat ~/.claude/settings.local.json 2>/dev/null | grep -A 50 '"plugins"'
+```
+
+Remove via Claude Code settings or by editing the plugins list directly:
+
+```bash
+# Backup first
+cp ~/.claude/settings.json ~/.claude/settings.json.bak
+
+# Then edit ~/.claude/settings.json to remove plugin entries
+# Remove entries like:
+#   "claude-for-financial-services"
+#   "bitwize-music"
+#   duplicate superpowers entries
+```
+
+Remove cached plugin directories:
+
+```bash
+cache_dir="$HOME/.claude/plugins/cache/<bundle-name>"
+if [ -d "$cache_dir" ]; then
+  rm -rf "$cache_dir"
+fi
+```
+
+### 5. Conditionally Load Heavy Skill Sets
+
+For language-specific bundles (e.g., `cc-skills-golang`):
+- Only install when actively working in that language
+- Uninstall when switching projects
+
+For security-focused skills (`secskills`):
+- Configure as manually invocable only (not auto-loaded)
+- In plugin settings: set `autoLoad: false` if supported
+
+### 6. Validate the Fix
+
+```bash
+# Restart Claude Code and check:
+# 1. No "Exceeded skills context budget" warning on startup
+# 2. /find-skills or skill listing shows descriptions (not empty)
+# 3. rtk gain shows reasonable context usage
+rtk gain 2>/dev/null || echo "rtk not available"
+```
+
+Open a new Claude Code session and run a skill that was previously failing — verify it activates correctly.
+
+### 7. Prevent Recurrence
+
+**Budget targets:**
+- Keep installed skills under ~200 total (rough safe limit)
+- Prefer curated skill sets over catch-all bundles
+- Review and prune quarterly
+
+**Useful heuristics:**
+- If you haven't invoked a skill in 30 days, the bundle is a candidate for removal
+- Language packs → install per-project, not globally
+- Duplicate superpowers/agent-skills versions → keep exactly one
+
+## Verification
+
+- [ ] No "Exceeded skills context budget" warning in new session
+- [ ] Skill descriptions visible in `/find-skills` output
+- [ ] Previously failing skill invocations succeed
+- [ ] Plugin count reduced to below ~20 bundles
+- [ ] `~/.claude/settings.json` backed up before changes

package/packages/software-development/skill-budget-audit/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-skill-budget-audit",
+  "description": "Diagnose and fix Claude Code skill context budget overflow — identify heavy plugin bundles, remove domain-specific ones, and restore skill discoverability.",
+  "skills": "./skills"
+}

package/packages/software-development/skill-budget-audit/adapters/claude/skills/skill-budget-audit/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: skill-budget-audit
+description: Diagnose and fix Claude Code's skill context budget overflow — identify heavy plugin bundles that exceed the 2% budget, remove domain-specific ones, deactivate rarely-used skill sets, and validate the warning clears. Use when Claude Code shows "Exceeded skills context budget" or skill descriptions are stripped.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Claude Code only. Requires access to ~/.claude/ and ~/.claude/plugins/
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - claude-code
+    - skills
+    - plugins
+    - context-budget
+    - token-economy
+    - performance
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · Skill context budget overflow appeared in 2 sessions this week (Jun 2026): initial investigation (7 turns, 742 skills hidden) and cleanup followup (14 turns)*
+
+# Skill Context Budget Audit
+
+## Overview
+
+Claude Code allocates 2% of its context window for skill descriptions. With too many plugins installed, descriptions get stripped and skills become invisible. This skill audits plugin bundles, removes unused domain-specific ones, and restores skill discoverability.
+
+## When to Use
+
+- Claude Code shows: `⚠ Exceeded skills context budget of 2%. All skill descriptions were removed and N additional skills hidden.`
+- Skill invocations fail silently or Claude cannot find a skill by name
+- After installing multiple plugin bundles, noticing slowdown or skill lookup failures
+- Periodically as a maintenance step when adding new skill collections
+
+## Workflow
+
+### 1. Confirm the Symptom
+
+```bash
+# Check Claude Code logs for context budget warning
+cat ~/.claude/logs/claude-code.log 2>/dev/null | grep -i "skill" | tail -20
+
+# Or count installed plugins
+ls ~/.claude/plugins/cache/ | wc -l
+```
+
+If you see `Exceeded skills context budget` or more than ~20 plugin bundles, proceed.
+
+### 2. Inventory Installed Plugins
+
+```bash
+# List all installed plugins with size
+du -sh ~/.claude/plugins/cache/*/ 2>/dev/null | sort -rh | head -30
+
+# Count skills per bundle
+for dir in ~/.claude/plugins/cache/*/; do
+  count=$(find "$dir" -name "*.md" -path "*/skills/*" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$count  $dir"
+done | sort -rn | head -20
+```
+
+### 3. Identify Removal Candidates
+
+Remove bundles that match any of these criteria:
+
+| Criterion | Example bundles |
+|-----------|----------------|
+| Domain not active in current projects | `claude-for-financial-services`, `bitwize-music` |
+| Duplicate superpowers installations | Multiple `superpowers-*` versions |
+| Language-specific bundles for inactive languages | `cc-skills-golang` when not working in Go |
+| Bundles with 30+ skills you never invoke | Large catch-all collections |
+
+Keep: core workflow skills (superpowers, agent-skills), project-specific skills, personal skill collections.
+
+### 4. Remove Heavy Bundles
+
+```bash
+# List Claude Code plugins (check settings.json for registered ones)
+cat ~/.claude/settings.json | grep -A 50 '"plugins"'
+# or
+cat ~/.claude/settings.local.json 2>/dev/null | grep -A 50 '"plugins"'
+```
+
+Remove via Claude Code settings or by editing the plugins list directly:
+
+```bash
+# Backup first
+cp ~/.claude/settings.json ~/.claude/settings.json.bak
+
+# Then edit ~/.claude/settings.json to remove plugin entries
+# Remove entries like:
+#   "claude-for-financial-services"
+#   "bitwize-music"
+#   duplicate superpowers entries
+```
+
+Remove cached plugin directories:
+
+```bash
+cache_dir="$HOME/.claude/plugins/cache/<bundle-name>"
+if [ -d "$cache_dir" ]; then
+  rm -rf "$cache_dir"
+fi
+```
+
+### 5. Conditionally Load Heavy Skill Sets
+
+For language-specific bundles (e.g., `cc-skills-golang`):
+- Only install when actively working in that language
+- Uninstall when switching projects
+
+For security-focused skills (`secskills`):
+- Configure as manually invocable only (not auto-loaded)
+- In plugin settings: set `autoLoad: false` if supported
+
+### 6. Validate the Fix
+
+```bash
+# Restart Claude Code and check:
+# 1. No "Exceeded skills context budget" warning on startup
+# 2. /find-skills or skill listing shows descriptions (not empty)
+# 3. rtk gain shows reasonable context usage
+rtk gain 2>/dev/null || echo "rtk not available"
+```
+
+Open a new Claude Code session and run a skill that was previously failing — verify it activates correctly.
+
+### 7. Prevent Recurrence
+
+**Budget targets:**
+- Keep installed skills under ~200 total (rough safe limit)
+- Prefer curated skill sets over catch-all bundles
+- Review and prune quarterly
+
+**Useful heuristics:**
+- If you haven't invoked a skill in 30 days, the bundle is a candidate for removal
+- Language packs → install per-project, not globally
+- Duplicate superpowers/agent-skills versions → keep exactly one
+
+## Verification
+
+- [ ] No "Exceeded skills context budget" warning in new session
+- [ ] Skill descriptions visible in `/find-skills` output
+- [ ] Previously failing skill invocations succeed
+- [ ] Plugin count reduced to below ~20 bundles
+- [ ] `~/.claude/settings.json` backed up before changes

package/scripts/build-adapters.sh

@@ -55,11 +55,13 @@ const plugins = [
   },
 ]
 
-const cursorPlugins = catalog.packages.map((pkg) => ({
-  name: lookupNameFor(pkg),
-  source: `./${pkg.path}/adapters/cursor`,
-  description: pkg.description,
-}))
+const cursorPlugins = catalog.packages
+  .filter((pkg) => pkg.adapters.includes('cursor'))
+  .map((pkg) => ({
+    name: lookupNameFor(pkg),
+    source: `./${pkg.path}/adapters/cursor`,
+    description: pkg.description,
+  }))
 
 fs.mkdirSync(path.join(root, '.claude-plugin'), { recursive: true })
 fs.mkdirSync(path.join(root, '.cursor-plugin'), { recursive: true })
@@ -127,7 +129,7 @@ const copilotInstructions = [
   '- Prefer small, scoped updates that preserve existing package structure.',
   '',
   'Available reusable prompt files:',
-  ...catalog.packages.map((pkg) => `- ${pkg.name}: .github/prompts/${promptNameFor(pkg)}`),
+  ...catalog.packages.filter((pkg) => pkg.adapters.includes('copilot')).map((pkg) => `- ${pkg.name}: .github/prompts/${promptNameFor(pkg)}`),
   '',
 ].join('\n')
 
@@ -138,7 +140,7 @@ for (const pkg of catalog.packages) {
     continue
   }
 
-  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimEnd()
+  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimStart().trimEnd()
   const prompt = stripTrailingLineWhitespace([
     generatedHeader,
     '',
@@ -160,7 +162,7 @@ for (const pkg of catalog.packages) {
     continue
   }
 
-  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimEnd()
+  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimStart().trimEnd()
   const content = stripTrailingLineWhitespace([
     generatedHeader,
     '',
@@ -180,7 +182,7 @@ for (const pkg of catalog.packages) {
     continue
   }
 
-  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimEnd()
+  const skillBody = stripFrontmatter(fs.readFileSync(skillPathFor(pkg), 'utf8')).trimStart().trimEnd()
   const content = stripTrailingLineWhitespace([
     generatedHeader,
     '',