Skills Smart Manager

---
name: skills-smart-manager
description: Meta-skill for skill lifecycle management. Monitors active skills, optimizes context window by unloading stale skills, detects dependency conflicts, recommends skills based on project type, performs health checks on MCP servers and APIs, and archives session memory for efficient future loading. Use when user says "optimize skills", "clean up context", "manage skills", "free tokens", "skill health check", "session feels slow", or when context >60% and multiple skills loaded. Also auto-triggers on project type switches (e.g., "done with Figma, let's code Rust").
metadata:
  author: valorisa
  version: 1.0.0
  category: meta-management
  requires: [bash, python3]
---

# 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

```bash
/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:

```bash
python3 scripts/analyze_context.py --action scan
```

**Expected output:**

```json
{
  "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:

```markdown
### 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)

```bash
# 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:

```bash
python3 scripts/analyze_context.py --action archive
```

**Output:** `.skill-memory.json` in project root

```json
{
  "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:

```bash
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:

| 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:**

```bash
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:**

```bash
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:

   ```text
   Load the [skill-name] skill again
   ```

2. Adjust staleness threshold in script:

   ```bash
   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`:

```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:

```bash
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](/CONTRIBUTING.md) for guidelines.

---

## License

MIT License — Part of valorisa/Claude-Skills collection