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:

Context Bloat Prevention — Detects and unloads skills not invoked in >15 turns
Dependency Management — Ensures prerequisite skills are active
Smart Recommendations — Suggests skills based on project files (Cargo.toml → rust skills)
Health Checks — Verifies MCP servers and API endpoints are responding
Garbage Collection — Cleans up temporary files generated by other skills
Conflict Detection — Identifies contradictory skills (e.g., formatters with conflicting rules)
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:

MCP servers are reachable (/ping endpoint)
Required API keys are set (GitHub token, OpenAI key, etc.)
CLI tools are installed (gh, docker, cargo, etc.)
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:

Skill auto-triggers (matches "sluggish" + "session")
Run analyze_context.py --action scan
Discover 8 heavy documentation skills loaded from previous project work

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)

User approves → unload all 8
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:

Skill auto-triggers (matches domain switch phrase)
Run analyze_context.py --action scan
Detect:
- figma-handoff currently active
- design-system currently active
- Working directory now contains Cargo.toml

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?

User approves → swap skills
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:

Skill auto-triggers (formatting issue likely skill conflict)
Run analyze_context.py --action scan
Detect conflict:
- prettier-formatter active (priority: 5)
- standard-js-linter active (priority: 3)
- Both modify JavaScript formatting

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

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

User approves → unload conflicting skill

Result: Consistent formatting behavior.

Action Matrix

Quick reference for common scenarios:

Symptom	Root Cause	Action
Session slow, high context %	Too many stale skills	Scan → unload unused
Formatting inconsistent	Conflicting formatter skills	Detect conflict → resolve
Skill not working	Missing dependency skill	Check dependencies → load prereqs
Domain switch	Skills from old domain still loaded	Detect switch → swap skills
API errors	MCP server down	Health check → restart or disable
Unknown project	First time in repo	Detect project type → recommend skills
Temp files everywhere	Skills not cleaning up	Garbage collect → delete temps

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:

Skill metadata is preserved. Reactivate instantly:
```
Load the [skill-name] skill again
```

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:

Edit references/conflict-rules.md
Remove or adjust the conflicting rule entry
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

About this skill

Overview

When to Use This Skill

Automatic Triggers

Manual Invocation

Instructions

Step 1: Analyze Current Session State

Step 2: Evaluate Skill Relevance

Criterion 1: Staleness

Criterion 2: Domain Mismatch

Criterion 3: Conflicts

Step 3: Recommend Actions

Step 4: Execute Optimization (if approved)

Step 5: Archive Session Memory (optional)

Step 6: Health Check (Optional Proactive Mode)

Examples

Example 1: Session Feels Slow

Example 2: Project Domain Switch

Example 3: Conflict Detection

Action Matrix

Garbage Collection Rules

Troubleshooting

Issue: analyze_context.py returns "Permission denied"

Issue: Unloaded a skill that was still needed

Issue: False positive conflict detection

Issue: Recommended skill doesn't exist

Progressive Disclosure

Skill Dependencies

Integration with Other Skills

Works well with

Conflicts with

Advanced: Automatic Background Mode

Metrics

Philosophy

Contributing

License

Issue: `analyze_context.py` returns "Permission denied"