/optimize-skills

Real-time skill optimization and improvement recommendations based on accumulated session learnings.

Usage

/optimize-skills              # Quick optimization check
/optimize-skills --full       # Full analysis with recommendations
/optimize-skills --skill X    # Analyze specific skill
/optimize-skills --apply      # Apply auto-improvements (with confirmation)
/optimize-skills --project PILOT  # Project-scoped analysis (ADR-159)

What This Command Does

1. Analyzes accumulated skill learnings from all sessions
2. Identifies skills with declining performance or high failure rates
3. Detects anti-patterns that reduce effectiveness
4. Generates prioritized improvement recommendations
5. Optionally applies auto-improvements with user confirmation

Quick Mode (Default)

Shows dashboard with:

• Overall skill health summary
• Top performers and underperformers
• Active anti-pattern alerts
• P0 (critical) recommendations

Full Mode (--full)

Complete analysis including:

• Success and failure pattern analysis
• Trend analysis over last 30 days
• All prioritized recommendations
• Specific action items per skill

Implementation

When /optimize-skills is invoked:

Step 1: Load Learnings

# Load accumulated skill learnings
learnings = load_file("context-storage/skill-learnings.json")

Step 2: Calculate Health Scores

For each tracked skill, calculate:

• Success Rate: successful invocations / total invocations
• Trend Score: recent performance vs historical
• Error Penalty: based on recurring errors
• Health Score: weighted combination (target: >80%)

Step 3: Detect Anti-Patterns

Check for common anti-patterns:

• excessive_retries - Multiple retry attempts
• context_confusion - Misunderstood task scope
• tool_misuse - Wrong tool selection
• incomplete_output - Missing expected elements
• hallucination_risk - Ungrounded assumptions

Step 4: Generate Recommendations

Prioritized recommendations by severity:

• P0: Critical skills (<50% health) - immediate revision needed
• P1: Needs work (50-70% health) - targeted improvements
• P2: Declining performance - investigate changes
• P3: Minor optimizations - nice to have

Step 5: Display Results

════════════════════════════════════════════════════════════════════════
                    SKILL HEALTH DASHBOARD
════════════════════════════════════════════════════════════════════════

📊 Overview: 15 skills tracked
   🟢 Excellent: 5
   🟡 Good: 7
   🟠 Needs Work: 2
   🔴 Critical: 1

🏆 Top Performers:
   git-workflow: 95% (excellent)
   code-editor: 92% (excellent)
   context-optimization: 88% (good)

⚠️ Needs Attention:
   deployment: 45% (critical)
   database-patterns: 62% (needs_work)

🚨 Anti-Pattern Alerts:
   🔴 excessive_retries: 8 occurrences (increasing)
   🟠 context_confusion: 3 occurrences (stable)

🔥 P0 - Immediate Action Required:
   [critical_skill] deployment
      Action: Major revision required

════════════════════════════════════════════════════════════════════════

Examples

Check Skill Health

User: /optimize-skills

Claude: Running skill optimization check...

📊 Skill Health Dashboard

15 skills tracked across 42 sessions.

✅ 12 skills healthy (>80%)
⚠️ 2 skills need attention (50-80%)
🔴 1 skill critical (<50%)

Priority Actions:
1. [P0] deployment skill: 45% health - Review failures
2. [P1] database-patterns: 62% health - Add examples
3. [P2] context-compression: Declining trend detected

Run `/optimize-skills --full` for detailed analysis.

Analyze Specific Skill

User: /optimize-skills --skill deployment

Claude: Analyzing deployment skill...

📊 Skill: deployment
   Health Score: 45% (critical)
   Total Invocations: 23
   Success Rate: 39%
   Common Errors:
   - "Kubernetes context not set"
   - "Image pull backoff"

📈 Trend: Declining (72% → 45% over 10 sessions)

💡 Recommendations:
1. Add Kubernetes context verification step
2. Include image registry authentication check
3. Add rollback examples
4. Expand troubleshooting section

Example improvement for SKILL.md:
```yaml
## Prerequisites (Learned)
- Verify kubectl context: `kubectl config current-context`
- Check image registry access: `gcloud auth print-access-token`

Apply these improvements? [y/N]

### Full Analysis

User: /optimize-skills --full

Claude: Running full skill pattern analysis...

═══ SKILL PATTERN ANALYSIS ═══

📊 Success Patterns (5 skills) git-workflow: High success rate (95%) code-editor: Consistent performance

📉 Failure Patterns (3 skills) deployment: High failure rate (39%) database-patterns: Recurring errors

🚨 Anti-Patterns (2 types) excessive_retries: 8 occurrences, increasing trend context_confusion: 3 occurrences, stable

📈 30-Day Trends Sessions analyzed: 42 Top improved: context-optimization (+15%) Top declined: deployment (-27%)

💡 Prioritized Recommendations (8 total)

P0 - Critical:

1. deployment: Major revision required
   • Review 14 failures
   • Add pre-flight checks
   • Include common error solutions

P1 - High Priority: 2. database-patterns: Targeted improvements

• Address recurring errors
• Add schema examples

3. excessive_retries anti-pattern
   • Add clearer pre-conditions to affected skills

P2 - Medium Priority: 4. context-confusion: Improve skill boundaries 5. monitoring: Add integration examples

═══ END ANALYSIS ═══

## Integration with Learning Loop

This command is part of the **Continual Learning Loop**:

Session Start → Load Learnings → Execute → Track Outcomes → Session End ↑ │ │ ▼ └─────── /optimize-skills ←────── Run Retrospective

### At Session Start
- Run `/optimize-skills` to see current health
- Note any P0/P1 recommendations
- Be aware of anti-patterns to avoid

### During Session
- Skills are tracked automatically
- Anti-patterns detected in real-time
- Outcomes recorded for analysis

### At Session End
- Run `/optimize-skills --full` for complete analysis
- Review recommendations
- Optionally apply improvements

## Related Commands

| Command | Purpose |
|---------|---------|
| `/retrospective` | Run session retrospective |
| `/cx` | Capture session context |
| `/cxq` | Query past learnings |
| `/orient` | Session orientation with skill loading |

## Related Scripts

```bash
# Full pattern analysis
python3 scripts/skill-pattern-analyzer.py --analyze

# Dashboard view
python3 scripts/skill-pattern-analyzer.py --dashboard

# Export report
python3 scripts/skill-pattern-analyzer.py --export-report

# Real-time optimization
python3 hooks/session-retrospective.py --optimize-now

Related Skills

• skill-improvement-tracker - Full tracking methodology
• context-optimization - Context efficiency patterns
• moe-task-execution - Task execution with skill routing

Success Output

When optimization check completes successfully:

✅ COMMAND COMPLETE: /optimize-skills
Skills tracked: N
Health score: X%
Critical (P0): M
Recommendations generated: Y

Completion Checklist

Before marking complete:

• Learnings loaded from JSON
• Health scores calculated
• Anti-patterns detected
• Dashboard displayed
• Recommendations prioritized

Failure Indicators

This command has FAILED if:

• ❌ skill-learnings.json not found
• ❌ No skills tracked yet
• ❌ Analysis script crashed
• ❌ Dashboard display error

When NOT to Use

Do NOT use when:

• No retrospectives run yet (no data)
• Immediately after /retrospective (data identical)
• During active task execution (wait for completion)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Ignore P0 recommendations	Skill failures continue	Address critical items first
Run without data	Empty results	Run /retrospective first
Skip --full mode	Miss detailed insights	Use --full for deep analysis

Principles

This command embodies:

• #9 Based on Facts - Data-driven optimization
• #1 Recycle, Extend, Re-Use - Improves existing skills
• #3 Complete Execution - Full analysis pipeline

Full Standard: CODITECT-STANDARD-AUTOMATION.md

---

Status: Active Invocable: Yes Category: Optimization