Skills Smart Manager

Skills Smart Manager

Overview

Core principle: Skills should be loaded only when actively needed. Stale or irrelevant skills waste precious context tokens, slow down response times, and can create conflicts.

This meta-skill acts as an orchestrator for your entire skill ecosystem. It monitors, analyzes, and optimizes the lifecycle of all active skills throughout your Claude Code sessions.

Key capabilities:

1. Context Bloat Prevention — Detects and unloads skills not invoked in >15 turns
2. Dependency Management — Ensures prerequisite skills are active
3. Smart Recommendations — Suggests skills based on project files (Cargo.toml → rust skills)
4. Health Checks — Verifies MCP servers and API endpoints are responding
5. Garbage Collection — Cleans up temporary files generated by other skills
6. Conflict Detection — Identifies contradictory skills (e.g., formatters with conflicting rules)
7. Session Memory — Archives optimal skill configuration per repository

When to Use This Skill

Automatic Triggers

• Context window >60% and ≥3 skills loaded
• User switches project domains ("done with design, let's code")
• Session feels slow or unresponsive
• Rate limit warnings appear

Manual Invocation

/skills-smart-manager

Or mention:

• "optimize my skills"
• "clean up loaded skills"
• "why is this session slow?"
• "manage my context"
• "skill health check"

Instructions

Step 1: Analyze Current Session State

Run the context analyzer to get a complete picture:

python3 scripts/analyze_context.py --action scan

Expected output:

{
  "active_skills": ["tdd-hybrid", "token-optimization", "rescue-tokens", "diagnose"],
  "last_invoked": {
    "tdd-hybrid": 2,
    "token-optimization": 0,
    "rescue-tokens": 18,
    "diagnose": 45
  },
  "estimated_token_footprint": {
    "tdd-hybrid": 3200,
    "token-optimization": 2800,
    "rescue-tokens": 1900,
    "diagnose": 2400
  },
  "total_skill_tokens": 10300,
  "context_percentage": 68,
  "project_type_detected": "rust-cargo"
}

Step 2: Evaluate Skill Relevance

Apply garbage collection criteria:

Criterion 1: Staleness

Skill not invoked for >15 user/assistant interaction turns.

Rationale: If a skill hasn't been needed recently, it's probably not relevant to current work.

Criterion 2: Domain Mismatch

Project files changed in a way that makes the skill irrelevant.

Examples:

• figma-handoff skill active, but no .fig files in working directory
• rust-best-practices skill active, but Cargo.toml was deleted
• docker-compose skill active, but docker-compose.yml removed

Criterion 3: Conflicts

Skill contradicts a higher-priority active skill.

Common conflicts (see references/conflict-rules.md):

• Multiple formatter skills (Prettier vs Standard vs custom rules)
• Multiple linter skills with incompatible rule sets
• Multiple testing framework skills (Jest vs Vitest)

Step 3: Recommend Actions

Based on analysis, prepare a recommendation report for the user:

### Skills Smart Manager Report

**Context Status:** 68% full (10,300 tokens from skills alone)

**Recommendations:**

1. **UNLOAD** `diagnose` — Not used in 45 turns, saving ~2,400 tokens
2. **UNLOAD** `token-optimization` — Not used this session, saving ~2,800 tokens
3. **KEEP** `tdd-hybrid` — Active (last used 2 turns ago)
4. **KEEP** `rescue-tokens` — Active (last used 18 turns ago, but relevant to context pressure)

**Detected Project Type:** Rust/Cargo

**Missing Recommended Skills:**
- `rust-best-practices` — Cargo.toml detected
- `cargo-optimizer` — Recommended for Rust projects

**Total Potential Savings:** ~5,200 tokens (50% reduction in skill footprint)

**Apply these changes?** (yes/no)

Step 4: Execute Optimization (if approved)

# Unload specific skill
python3 scripts/analyze_context.py --action unload --skill diagnose

# Or batch unload multiple
python3 scripts/analyze_context.py --action unload --skills diagnose,token-optimization

Step 5: Archive Session Memory (optional)

If this is a repository the user works in frequently, create a .skill-memory.json file:

python3 scripts/analyze_context.py --action archive

Output: .skill-memory.json in project root

{
  "repository": "github.com/user/project",
  "project_type": "rust-cargo",
  "recommended_skills": ["tdd-hybrid", "rust-best-practices", "cargo-optimizer"],
  "avoid_skills": ["diagnose", "token-optimization"],
  "last_updated": "2026-05-28T18:45:00Z"
}

Benefit: Next session in this repo will pre-load optimal skills automatically.

Step 6: Health Check (Optional Proactive Mode)

Verify that dependencies for active skills are healthy:

python3 scripts/analyze_context.py --action health-check

Checks performed:

1. MCP servers are reachable (/ping endpoint)
2. Required API keys are set (GitHub token, OpenAI key, etc.)
3. CLI tools are installed (gh, docker, cargo, etc.)
4. File paths referenced in skills exist

Example output:

✅ GitHub MCP — Responding (72ms)
❌ OpenAI API — Key not found in environment
✅ `gh` CLI — Installed (v2.40.1)
⚠️  `docker` — Installed but daemon not running

Examples

Example 1: Session Feels Slow

User says: "This session is really sluggish today. What's going on?"

Actions:

1. Skill auto-triggers (matches "sluggish" + "session")

2. Run analyze_context.py --action scan

3. Discover 8 heavy documentation skills loaded from previous project work

4. Present report:

   Found 8 skills using ~18,000 tokens that haven't been invoked this session:
   - vercel:deployment-expert (4,200 tokens)
   - vercel:performance-optimizer (3,800 tokens)
   - docker-compose-wizard (2,900 tokens)
   - ...
   
   Recommendation: Unload all 8 → saves 18,000 tokens (42% context reduction)
   

5. User approves → unload all 8

6. Confirm: "Context optimized. Freed 18,000 tokens. Session should be faster now."

Result: Context reduced from 78% to 36%, response latency improves.

Example 2: Project Domain Switch

User says: "Okay, I'm done with the Figma design work. Let's switch to writing the Rust backend."

Actions:

1. Skill auto-triggers (matches domain switch phrase)

2. Run analyze_context.py --action scan

3. Detect:

   • figma-handoff currently active
   • design-system currently active
   • Working directory now contains Cargo.toml

4. Present recommendation:

   Domain switch detected: Design → Rust Backend
   
   **Unload:**
   - figma-handoff (no longer relevant)
   - design-system (no longer relevant)
   
   **Load:**
   - rust-best-practices (Cargo.toml detected)
   - cargo-optimizer (recommended for Rust projects)
   
   Proceed?
   

5. User approves → swap skills

6. Confirm: "Skills updated. Ready for Rust development."

Result: Context stays clean, relevant skills active.

Example 3: Conflict Detection

User says: "Why is my code being formatted inconsistently?"

Actions:

1. Skill auto-triggers (formatting issue likely skill conflict)

2. Run analyze_context.py --action scan

3. Detect conflict:

   • prettier-formatter active (priority: 5)
   • standard-js-linter active (priority: 3)
   • Both modify JavaScript formatting

4. Check references/conflict-rules.md:

   CONFLICT: prettier-formatter vs standard-js-linter
   Reason: Overlapping formatting rules
   Resolution: Keep higher priority (prettier-formatter), unload standard-js-linter
   

5. Present recommendation:

   Conflict detected:
   - prettier-formatter (priority 5)
   - standard-js-linter (priority 3)
   
   These skills have overlapping formatting rules.
   
   Recommendation: Keep prettier-formatter, unload standard-js-linter
   

6. User approves → unload conflicting skill

Result: Consistent formatting behavior.

Action Matrix

Quick reference for common scenarios:

Garbage Collection Rules

Skills often generate temporary files. Clean these up automatically:

Common temporary artifacts:

• *.skill-temp.* — General skill temp files
• .claude-export-*.pdf — PDF exports
• .skill-cache/ — Skill cache directories
• diagnose-*.log — Diagnostic logs
• llm-council-report-*.md — Council reports (unless user saved them)

Cleanup command:

python3 scripts/analyze_context.py --action gc

Safety: Only deletes files matching known temporary patterns. Never deletes user files.

Troubleshooting

Issue: analyze_context.py returns "Permission denied"

Cause: Script doesn't have execute permission or can't access .claude/settings.json

Fix:

chmod +x /Users/valorisa/.claude/skills/skills-smart-manager/scripts/analyze_context.py

Or manually disable skills via /skills command.

Issue: Unloaded a skill that was still needed

Cause: Staleness threshold (15 turns) too aggressive for your workflow

Fix:

1. Skill metadata is preserved. Reactivate instantly:

   Load the [skill-name] skill again
   

2. Adjust staleness threshold in script:

   python3 scripts/analyze_context.py --action scan --staleness-threshold 30
   

Issue: False positive conflict detection

Cause: references/conflict-rules.md has incorrect rule

Fix:

1. Edit references/conflict-rules.md
2. Remove or adjust the conflicting rule entry
3. Re-run scan

Issue: Recommended skill doesn't exist

Cause: Project type detection suggests skill not in your collection

Fix:

Recommendations are just suggestions. You can:

• Ignore the suggestion
• Install the recommended skill from community
• Update project type mappings in references/project-type-skills.json

Progressive Disclosure

Level 1 (This document): High-level instructions and action matrix

Level 2 (Supporting files):

• scripts/analyze_context.py — Core analysis engine
• references/conflict-rules.md — Skill conflict resolution rules
• references/project-type-skills.json — Project type → recommended skills mapping
• assets/report-template.md — Template for user-facing reports

Level 3 (Script internals):

See scripts/analyze_context.py --help for full CLI documentation.

Skill Dependencies

This skill depends on:

• Python 3.7+ (for analysis script)
• Bash (for file operations)
• Access to .claude/ directory (read skill metadata)

Optional:

• jq (for JSON parsing in shell scripts)
• Git (for repository detection)

Integration with Other Skills

Works well with

• token-optimization — Shares same goal (reduce token waste)
• rescue-tokens — Emergency counterpart (this is proactive, that's reactive)
• setup-matt-pocock-skills — Configures skill infrastructure

Conflicts with

• None known

Advanced: Automatic Background Mode

For power users: Enable automatic background optimization.

Add to .claude/settings.json:

{
  "hooks": {
    "on-context-threshold": {
      "threshold": 60,
      "command": "python3 ~/.claude/skills/skills-smart-manager/scripts/analyze_context.py --action scan --auto-unload"
    }
  }
}

Behavior: When context hits 60%, automatically unload stale skills without prompting.

Risk: Might unload skills you still need. Use with caution.

Metrics

Track optimization impact over time:

python3 scripts/analyze_context.py --action metrics

Output:

Skills Smart Manager — Session Metrics

Total optimizations performed: 12
Total tokens saved: 87,400
Average session context: 34% (down from 68%)
Skills unloaded: 23
Skills reloaded: 4
False positives: 1 (4% rate)

Most commonly unloaded skills:
1. diagnose (8 times)
2. token-optimization (7 times)
3. vercel:deployment-expert (5 times)

Philosophy

Skills are tools, not decorations. Just like you wouldn't keep every tool in your toolbox open on your workbench, you shouldn't keep every skill loaded in your context.

Load when needed. Unload when done.

This skill enforces that discipline automatically.

Contributing

Found a better heuristic for staleness detection? Discovered a new conflict pattern? Contributions welcome!

See project CONTRIBUTING.md for guidelines.

License

MIT License — Part of valorisa/Claude-Skills collection