Skill Maintenance Skill

Skill Maintenance Skill

Systematic monthly maintenance for skill libraries to ensure 100% activation rate.

Quick Start

# Run monthly audit (Week 1)
for skill in ~/.claude/skills/*-skill/SKILL.md; do
    if ! grep -q "Use when" "$skill" 2>/dev/null; then
        echo "❌ $(basename $(dirname $skill))"
    fi
done | tee /tmp/skill-audit.txt

# Count results
echo "Missing 'Use when': $(cat /tmp/skill-audit.txt | wc -l)"

Monthly Schedule

Week 1: Audit Check

• Run bulk audit script
• Target: 0 skills missing "Use when"
• Fix any gaps immediately

Week 2: Fresh Session Testing

Test 10 natural language queries:

1. "we have issue with [domain]"
2. "test the [feature]"
3. "check [system] status"
4. "deploy to [environment]"
5. "[domain] not working"

Target: 80% activation rate, 90% correct skill

Week 3: Gap Analysis

If targets not met:

1. Identify failing patterns
2. Add synonym expansion to pre-prompt.sh
3. Update CRITICAL_KEYWORDS if needed
4. Create missing skills

Week 4: Documentation

• Update test guide with new tests
• Log results in roadmap
• Create Entry if significant changes

"Use when" Standard

Every skill MUST have:

description: "[What]. Use when [scenarios]."

Examples:

# ✅ GOOD
description: "Debug database issues. Use when seeing ECONNREFUSED, auth failures, or pool exhaustion."

# ❌ BAD
description: "Database skill."

Audit Script (Full)

#!/bin/bash
# skill-audit.sh - Monthly skill library audit

echo "=== SKILL LIBRARY AUDIT ==="
echo "Date: $(date)"
echo ""

TOTAL=0
MISSING=0

for skill in ~/.claude/skills/*-skill/SKILL.md; do
    [ -f "$skill" ] || continue
    TOTAL=$((TOTAL + 1))
    
    if ! grep -q "Use when" "$skill" 2>/dev/null; then
        MISSING=$((MISSING + 1))
        echo "❌ $(basename $(dirname $skill))"
    fi
done

echo ""
echo "=== SUMMARY ==="
echo "Total skills: $TOTAL"
echo "With 'Use when': $((TOTAL - MISSING))"
echo "Missing: $MISSING"
echo "Coverage: $(( (TOTAL - MISSING) * 100 / TOTAL ))%"

if [ $MISSING -eq 0 ]; then
    echo "✅ 100% coverage - audit passed!"
else
    echo "⚠️ Fix $MISSING skills to reach 100%"
fi

Fresh Session Test Script

#!/bin/bash
# test-skill-activation.sh - Fresh session activation test

TESTS=(
    "issue with database connection"
    "deploy to staging"
    "test the migration"
    "whatsapp webhook"
    "semantic query routing"
    "check cache status"
    "pr review needed"
    "sync gap detected"
    "visual regression test"
    "mcp postgres server"
)

echo "=== FRESH SESSION SKILL ACTIVATION TEST ==="
echo ""

for test in "${TESTS[@]}"; do
    echo "Query: \"$test\""
    result=$(echo "$test" | bash ~/.claude/hooks/pre-prompt.sh 2>/dev/null | grep -i skill | head -3)
    if [ -n "$result" ]; then
        echo "✅ Skills: $result"
    else
        echo "❌ No skills matched"
    fi
    echo ""
done

Gap Detection

When skill doesn't activate:

1. Check synonym expansion:

   grep -i "[keyword]" ~/.claude/hooks/pre-prompt.sh
   

2. Check CRITICAL_KEYWORDS:

   grep "CRITICAL_KEYWORDS" ~/.claude/hooks/pre-prompt.sh
   

3. Create missing skill if needed:

   mkdir -p ~/.claude/skills/[domain]-skill
   # Create SKILL.md with proper "Use when" pattern
   

Success Metrics

References

• Chapter 17: Skill Detection Enhancement
• Chapter 24: Skill Keyword Enhancement Methodology
• Entry #244: Phases 3+4 implementation