skills-smart-manager

Files (5)

• README.md
• SKILL.md
• report-template.md · assets/
• conflict-rules.md · references/
• analyze_context.py · scripts/

SKILL.md (first lines)

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

From valorisa/Claude-Skills, MIT.

More from valorisa/Claude-Skills