Pre-Prompt Hook System - Complete Implementation Guide

UPDATE (February 2026): Claude Code now natively loads all skills into context and performs its own matching. The custom UserPromptSubmit pre-prompt hook described in this guide is no longer necessary for skill activation. Claude Code’s built-in skill system handles discovery, matching, and activation automatically.

What changed: Claude Code’s native skill loading matured to handle 200+ skills natively. The hook’s custom Triggers: field, hybrid cache, and keyword scoring are now redundant with the built-in description-based matching.

Recommendation: Remove the UserPromptSubmit hook from .claude/settings.json. Keep skills in ~/.claude/skills/ with proper name: and description: (with “Use when…”) frontmatter - Claude Code discovers them automatically.

What to keep from this guide: The skill quality standards (frontmatter, “Use when” clauses, trigger keywords in descriptions, <500 line limit) remain best practices for native Claude Code skill discovery.

The pre-prompt hook is a UserPromptSubmit hook that automatically intercepts queries, matches them against a cached skill library using keyword scoring, and injects the top 3 matching skills into Claude’s context. This implementation achieved a 370x performance improvement (from 50 seconds to 136ms) and 88.2% activation accuracy across 170 test queries. It saves 85+ hours per year in production.

Author: Production dev-Knowledge Branch Performance: 370x optimization (50s -> 136ms) - Entry #267 Accuracy: 88.2% (150/170 tests) - Entry #271 ROI: 85+ hours/year saved - Entry #272 Status: Deprecated (Feb 2026) - Native Claude Code skill loading replaces this approach

🎯 What is the Pre-Prompt Hook?

The pre-prompt hook is a UserPromptSubmit hook that automatically:

Intercepts your query before Claude sees it
Matches against your skills library using keyword scoring
Ranks skills by relevance (scoring algorithm)
Injects top 3 matched skills into Claude’s context
Provides proactive recommendations

Result: Claude automatically has the right skill knowledge loaded before answering!

Before/After Comparison

WITHOUT Hook:
  - Claude uses generic knowledge
  - Inconsistent responses
  - Must manually reference skills
  - 61.1% accuracy (104/170 tests)

WITH Hook:
  - Automatic skill loading
  - Consistent, expert responses
  - Skills loaded proactively
  - 88.2% accuracy (150/170 tests)
  - 27.1% improvement (+46 tests)

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    USER QUERY                                │
│              "deploy to staging"                             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│            .claude/hooks/pre-prompt.sh                       │
│                                                              │
│  1. Load cache: ~/.claude/cache/skill-index-hybrid.txt      │
│  2. Parse query into keywords                                │
│  3. Score each skill against query                           │
│  4. Rank by score (keyword matches + priority)               │
│  5. Select top 3 matches                                     │
│  6. Generate proactive recommendations                       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                  MATCHED SKILLS                              │
│                                                              │
│  ✅ deployment-workflow-skill (rank #1, score 95.2)         │
│  ✅ cloud-run-safe-deployment-skill (rank #2, score 87.3)   │
│  ✅ post-deployment-validation-skill (rank #3, score 82.1)  │
│                                                              │
│  🚀 DEPLOYMENT: deployment-workflow-skill, ...              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              INJECTED INTO CLAUDE'S CONTEXT                  │
│                                                              │
│  Claude now has deployment skills loaded automatically       │
│  Uses deployment patterns to answer accurately               │
└─────────────────────────────────────────────────────────────┘

Performance Metrics

Entry #267 (Optimization):
  Before: 50 seconds (unoptimized matching)
  After: 136ms (hybrid cache system)
  Improvement: 99.7% reduction (370x faster)

Entry #271 (Accuracy):
  Before: 61.1% (104/170)
  After: 88.2% (150/170)
  Improvement: +27.1% (+46 tests)

Entry #272 (Sustainability):
  Automation: 85+ hours/year saved
  Cache Coverage: 100% (184/184 skills)
  Monitoring: Weekly health checks

🚀 Step-by-Step Setup

Step 1: Create Hook Script

Location: .claude/hooks/pre-prompt.sh

Option A: Copy from Production (Recommended)

# If you have access to Production repository:
curl -o .claude/hooks/pre-prompt.sh \
  https://raw.githubusercontent.com/ytrofr/production/dev-Knowledge/.claude/hooks/pre-prompt.sh

chmod +x .claude/hooks/pre-prompt.sh

Option B: Create from Scratch

Minimum viable pre-prompt.sh (simplified version):

#!/bin/bash

# Load skill cache
CACHE_FILE="$HOME/.claude/cache/skill-index-hybrid.txt"

if [ ! -f "$CACHE_FILE" ]; then
  # Build cache first time
  echo "Building skill cache..."
  # Logic to scan ~/.claude/skills/ and build cache
fi

# Parse input JSON
QUERY=$(echo "$1" | jq -r '.prompt' 2>/dev/null || echo "$1")

# Score skills against query
# (keyword matching logic here)

# Output top 3 matched skills
echo "✅ skill-name-1"
echo "✅ skill-name-2"
echo "✅ skill-name-3"

Full Implementation: See Production repository for complete 500-line version with:

Hybrid cache system (370x faster)
Advanced scoring algorithm
P0-P3 priority handling
Proactive recommendations
Error handling

Step 2: Create Skill Directory Structure

mkdir -p ~/.claude/skills
mkdir -p ~/.claude/cache
mkdir -p tests/skills/results

Step 3: Create Your First Skill

Example: ~/.claude/skills/deployment-workflow-skill/SKILL.md

---
name: deployment-workflow-skill
description: "Execute deployment workflow with validation and rollback. Use when deploying to staging/production, running gcloud deploy, or when user mentions 'deployment stuck'."
Triggers: deployment workflow, deploy, gcloud run deploy, deploy to staging, deploy to production, cloud run deploy, deployment process, gcloud deploy
---

# Deployment Workflow Skill

**Purpose**: Complete deployment workflow patterns
**Created**: 2026-01-15
**ROI**: 15 hours/year

## Quick Start

```bash
# Staging deployment
gcloud run deploy SERVICE-staging --source . --region us-central1

# Production deployment (after staging validation)
gcloud run deploy SERVICE-production --source . --region us-central1

When to Use

Deploying to staging/production
Running gcloud deploy commands
Deployment stuck or not working
Post-deployment validation

Core Patterns

Pre-Deployment Checklist

Run tests: npm test
Check Sacred compliance: grep -r "pattern" src/
Build validation: npm run build

Deployment Commands

# Always deploy to staging first
gcloud run deploy SERVICE-staging --source .

# Validate staging works
curl https://SERVICE-staging.run.app/health

# Then deploy to production
gcloud run deploy SERVICE-production --source .

Post-Deployment Validation

# CRITICAL: Route traffic to latest revision!
gcloud run services update-traffic SERVICE --to-latest

# Verify deployment
curl https://SERVICE.run.app/health

cloud-run-safe-deployment-skill
post-deployment-validation-skill

**Key Requirements** (MANDATORY):

1. **YAML Frontmatter**:
   - `name:` field (lowercase-hyphen only)
   - `description:` field (<1024 chars, MUST include "Use when...")
   - `Triggers:` field (5-10 comma-separated keywords)

2. **Description Pattern** (Anthropic Official):

“[SPECIFIC ACTIONS with verbs]. Use when [scenarios] or when user mentions [keywords].”

3. **File Size**: Max 500 lines (Anthropic limit)

4. **Trigger Keywords**: Include exact user query phrases

### Step 4: Build Initial Cache

```bash
# Test your first skill
echo '{"prompt": "deploy to staging"}' | bash .claude/hooks/pre-prompt.sh

# Expected output:
# ✅ deployment-workflow-skill (rank #1, score 95.2)

If cache doesn’t exist, the hook will build it automatically.

Step 5: Create Test Suite

Location: tests/skills/comprehensive-skill-activation-test.sh

#!/bin/bash

# Test function
test_skill() {
  local expected="$1"
  local query="$2"
  local domain="$3"
  local priority="$4"

  # Run hook
  result=$(echo "{\"prompt\": \"$query\"}" | bash .claude/hooks/pre-prompt.sh)

  # Check if expected skill in top 3
  if echo "$result" | grep -q "✅ $expected"; then
    echo "PASS: $expected | $query"
  else
    echo "FAIL: $expected | $query | Got: $result"
  fi
}

# Add tests for your skills
test_skill "deployment-workflow-skill" "deploy to staging" "deployment" "P1"
test_skill "deployment-workflow-skill" "gcloud run deploy" "deployment" "P1"
test_skill "database-patterns-skill" "golden rule database" "database" "P1"

# Run all tests
echo "=== TEST RESULTS ==="
# Count PASS/FAIL

Step 6: Run First Test

bash tests/skills/comprehensive-skill-activation-test.sh

# Expected:
# PASS: deployment-workflow-skill | deploy to staging
# PASS: deployment-workflow-skill | gcloud run deploy
# ...
# Results: 3/3 PASS (100%)

🚨 Critical Cache Management

The Cache Staleness Problem (Entry #271 Discovery)

Problem: Cache only indexed 64/184 skills (35% coverage) even though all skills existed.

Root Cause: Hash-based validation doesn’t detect trigger keyword changes:

# Cache hash calculation:
SKILL_COUNT=$(ls -1 "$SKILLS_DIR" | wc -l)
NEWEST_MTIME=$(find "$SKILLS_DIR" -name "SKILL.md" -type f -printf '%T@\n' | sort -n | tail -1)
TOTAL_SIZE=$(find "$SKILLS_DIR" -name "SKILL.md" -type f -printf '%s\n' | awk '{sum+=$1} END {print sum}')
CACHE_HASH="${SKILL_COUNT}-${NEWEST_MTIME}-${TOTAL_SIZE}"

Issue: Trigger keyword updates don’t change count/size significantly → stale hash → stale cache → 65% of skills invisible!

Solution: Manual Cache Rebuild (MANDATORY)

# ALWAYS rebuild cache after modifying ANY skill:
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "test"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# Verify cache rebuilt:
wc -l ~/.claude/cache/skill-index-hybrid.txt
# Expected: N+1 (header + N skills)

When to Rebuild Cache

✅ ALWAYS rebuild after:

Created new skill
Modified skill triggers/description
Deleted skill
Renamed skill directory
Batch skill updates

Cache Health Check Script

Create scripts/cache-health-check.sh:

#!/bin/bash

echo "📊 Skill Cache Health Check"
echo "Date: $(date)"
echo ""

# Count filesystem skills
FS_COUNT=$(find ~/.claude/skills -name "SKILL.md" -type f | wc -l)
echo "Filesystem skills: $FS_COUNT"

# Count cache skills
CACHE_COUNT=$(( $(wc -l < ~/.claude/cache/skill-index-hybrid.txt 2>/dev/null || echo 0) - 1 ))
echo "Cached skills: $CACHE_COUNT"

# Calculate coverage
if [ "$FS_COUNT" -gt 0 ]; then
  COVERAGE=$(awk "BEGIN {printf \"%.1f\", ($CACHE_COUNT / $FS_COUNT) * 100}")
  echo "Coverage: $COVERAGE%"

  if (( $(echo "$COVERAGE < 95" | bc -l) )); then
    echo "⚠️  WARNING: Cache coverage below 95% - rebuild recommended"
    echo ""
    echo "Action: rm ~/.claude/cache/skill-index-hybrid.txt && rebuild"
  else
    echo "✅ Cache health: GOOD"
  fi
else
  echo "❌ No skills found in filesystem"
fi

Run weekly: bash scripts/cache-health-check.sh

🎯 Test Priority System

Priority Levels (Entry #271 Standard)

P0 (must be #1):
  Count: 2-5% of tests
  Criteria: Critical skill, no competing skills, must rank first
  Example: sacred-commandments-skill for "golden rule"
  Scoring: 100 points base

P1 (must be top 3):
  Count: 70-80% of tests
  Criteria: Important skill, competing skills exist, top 3 acceptable
  Example: deployment-workflow-skill for "deploy to staging"
  Scoring: 90 points base

P2 (must be present):
  Count: 15-25% of tests
  Criteria: Skill should appear in results, ranking less critical
  Example: archive-and-changelog-skill for "archive old files"
  Scoring: 80 points base

P3 (foundational pattern):
  Count: 10-20% of tests
  Criteria: Pattern in auto-loaded context, not standalone skill
  Example: financial-precision-skill → auto-loaded file
  Result: Auto-pass with status: PASS, position: pattern
  Scoring: N/A (validation only)

Test Format

test_skill "expected-skill-name" "user query" "domain" "P1"
#          ↑                      ↑            ↑        ↑
#          Expected skill         Query        Domain   Priority

Example Test Suite Structure

# Domain: Deployment (P1 tests)
test_skill "deployment-workflow-skill" "deploy to staging" "deployment" "P1"
test_skill "deployment-workflow-skill" "gcloud run deploy" "deployment" "P1"
test_skill "cloud-run-safe-deployment-skill" "safe deployment" "deployment" "P1"

# Domain: Database (P0 test for critical skill)
test_skill "sacred-commandments-skill" "golden rule" "sacred" "P0"

# Domain: Troubleshooting (P2 tests)
test_skill "troubleshooting-workflow-skill" "production error" "troubleshooting" "P2"

Production Results (170 tests)

P0 Tests: 3 (2%) - All passing (100%)
P1 Tests: 131 (77%) - 123 passing (93.9%)
P2 Tests: 36 (21%) - 27 passing (75%)
P3 Tests: 25 (15%) - All passing (100%)

Overall: 150/170 PASS (88.2%)

🔑 Trigger Optimization

5 Core Principles (Entry #271 Patterns)

1. Use Exact User Query Phrases

✅ CORRECT:
  Triggers: deployment workflow, gcloud run deploy, deploy to staging, gcloud deploy

❌ WRONG:
  Triggers: deployment workflow, deploy

Why: Adding exact phrases improved ranking from #3 → #1 in testing.

2. Include Command Variations

Triggers: gcloud deploy, gcloud run deploy, deploy staging, deploy production, cloud run deploy, deployment process

Coverage: User might say any of these variations.

3. Add Action + Object Patterns

Triggers: verify deployment, check deployment, validate deployment, deployment verification, deployment status

Pattern: [action verb] + [object noun]

4. Natural Language Variations

Triggers: deployment stuck, deployment not working, deployment failed, deploy error, deployment issues

Coverage: Users describe problems in natural language.

5. Avoid Generic Terms

❌ AVOID:
  - help
  - fix
  - issue
  - problem
  - task
  - work

✅ USE:
  - Specific domain terms (deployment, database, api)
  - Exact commands (gcloud deploy, npm test)
  - Precise scenarios (deployment stuck, api timeout)

Why: Generic terms match too many skills, dilute specificity.

Trigger Optimization Workflow

# 1. Run comprehensive test
bash tests/skills/comprehensive-skill-activation-test.sh

# 2. Find failures
cat tests/skills/results/skill-test-*.json | grep '"status":"FAIL"'

# 3. For each failure:
#    - Add exact query phrase to skill's Triggers
#    - Rebuild cache
#    - Re-test

# Example:
# FAIL: deployment-workflow-skill | gcloud run deploy production
# → Add "gcloud run deploy production" to Triggers

Recommended Trigger Count

Minimum: 5 triggers per skill
Optimal: 7-10 triggers per skill
Maximum: 15 triggers per skill

Too few: Miss valid queries
Too many: Dilutes specificity

📊 Weekly Monitoring (Entry #272)

Setup Weekly Health Check

Create scripts/weekly-skill-health-check.sh:

#!/bin/bash

echo "🏥 Weekly Skill Health Check"
echo "Date: $(date)"
echo "========================================="
echo ""

# 1. Cache Health
echo "📦 Cache Health:"
FS_COUNT=$(find ~/.claude/skills -name "SKILL.md" -type f | wc -l)
CACHE_COUNT=$(( $(wc -l < ~/.claude/cache/skill-index-hybrid.txt 2>/dev/null || echo 0) - 1 ))
COVERAGE=$(awk "BEGIN {printf \"%.1f\", ($CACHE_COUNT / $FS_COUNT) * 100}")

echo "  Filesystem: $FS_COUNT skills"
echo "  Cached: $CACHE_COUNT skills"
echo "  Coverage: $COVERAGE%"

if (( $(echo "$COVERAGE < 95" | bc -l) )); then
  echo "  ⚠️  WARNING: Rebuilding cache..."
  rm ~/.claude/cache/skill-index-hybrid.txt
  echo '{"prompt": "rebuild"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1
  echo "  ✅ Cache rebuilt"
fi
echo ""

# 2. Run Comprehensive Test
echo "🧪 Running Comprehensive Test:"
bash tests/skills/comprehensive-skill-activation-test.sh > /tmp/skill-test-weekly.txt

# Parse results
PASSED=$(grep -c "^PASS:" /tmp/skill-test-weekly.txt || echo 0)
TOTAL=$(grep -c -E "^(PASS|FAIL):" /tmp/skill-test-weekly.txt || echo 0)
ACCURACY=$(awk "BEGIN {printf \"%.1f\", ($PASSED / $TOTAL) * 100}")

echo "  Passed: $PASSED/$TOTAL ($ACCURACY%)"
echo ""

# 3. Compare with Last Week
LAST_WEEK=$(ls -t tests/skills/results/weekly-health-*.json 2>/dev/null | head -1)
if [ -f "$LAST_WEEK" ]; then
  LAST_ACCURACY=$(jq -r '.accuracy' "$LAST_WEEK" 2>/dev/null || echo "0")
  CHANGE=$(awk "BEGIN {printf \"%.1f\", $ACCURACY - $LAST_ACCURACY}")

  echo "📈 Week-over-Week:"
  echo "  Last week: $LAST_ACCURACY%"
  echo "  This week: $ACCURACY%"
  echo "  Change: $CHANGE%"

  if (( $(echo "$CHANGE < -2" | bc -l) )); then
    echo "  ⚠️  ALERT: Accuracy dropped >2% - investigation needed!"
  fi
fi
echo ""

# 4. Save Results
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
jq -n \
  --arg timestamp "$(date -Iseconds)" \
  --arg accuracy "$ACCURACY" \
  --arg passed "$PASSED" \
  --arg total "$TOTAL" \
  --arg cache_coverage "$COVERAGE" \
  '{timestamp: $timestamp, accuracy: ($accuracy | tonumber), passed: ($passed | tonumber), total: ($total | tonumber), cache_coverage: ($cache_coverage | tonumber)}' \
  > "tests/skills/results/weekly-health-$TIMESTAMP.json"

echo "✅ Health check complete!"
echo "Results saved: tests/skills/results/weekly-health-$TIMESTAMP.json"

Schedule Weekly Checks

Recommended: Every Monday 9:00 AM

Option 1: Cron (Linux/Mac)

crontab -e

# Add:
0 9 * * 1 cd /path/to/project && bash scripts/weekly-skill-health-check.sh

Option 2: Manual

Set calendar reminder: “Monday 9AM - Skill Health Check”

Weekly Checklist (10 minutes)

✅ Run health check: bash scripts/weekly-skill-health-check.sh
✅ Review accuracy >85%
✅ Verify cache coverage 100%
✅ Check for alerts
✅ Document findings if issues

Monthly Optimization (1st Monday, 30 minutes)

Run analytics: node scripts/skill-activation-analytics.js
Review recurring failures (3+ occurrences)
Optimize 5-10 trigger keywords
Rebuild cache and re-test
Document improvements

ROI Analysis

Weekly_Monitoring:
  Time: 50 min/week × 52 weeks
  Savings: 43.3 hours/year

Monthly_Optimization:
  Time: 40 min × 12 months
  Savings: 8 hours/year

Quality_Gates:
  Time: 25 min × 20 new skills
  Savings: 8.3 hours/year

Regression_Prevention:
  Time: 120 min × 5 incidents
  Savings: 10 hours/year

Cache_Debugging:
  Time: 60 min × 10 incidents
  Savings: 10 hours/year

Cleanup:
  Time: 80 min × 4 quarters
  Savings: 5.3 hours/year

TOTAL: 85+ hours/year automated

📊 Domain Performance

Production Results (170 tests across 12 domains)

Perfect (100%):
  Testing: 9/9 tests
  Sacred: 3/3 tests
  Hebrew: 2/2 tests
  Git: 1/1 test

Excellent (90%+):
  AI/LLM: 19/20 tests (95%)
  Troubleshooting: 17/18 tests (94.4%)
  API: 10/11 tests (90.9%)
  Sync: 9/10 tests (90%)

Good (80%+):
  Database: 28/34 tests (82.4%)
  Deployment: 24/31 tests (77.4%)

Needs Work (<80%):
  Context/Knowledge: 14/22 tests (63.6%)
  Frontend/UI: 8/16 tests (50%)
  Business: 6/13 tests (46.2%)

How to Improve Domain Performance

For domains <80%:

Add more test queries (expand coverage)
Optimize trigger keywords (add exact phrases)
Create domain-specific skills (reduce competition)
Consolidate duplicates (merge similar skills)

Example (Frontend/UI domain):

Current: 8/16 tests (50%)
Issue: Generic "ui" triggers match too broadly

Solution:
  1. Split into specific skills:
     - mobile-responsive-skill (mobile, responsive)
     - theme-migration-skill (theme, chakra, css)
     - dashboard-optimization-skill (dashboard, ui, layout)

  2. Add exact phrases:
     - "mobile not working" → mobile-responsive-skill
     - "theme broken" → theme-migration-skill
     - "dashboard layout" → dashboard-optimization-skill

  3. Re-test:
     Expected: 12/16 tests (75%) → 14/16 tests (87.5%)

⚡ Quick Commands

Testing

# Test single query
echo '{"prompt": "your query here"}' | bash .claude/hooks/pre-prompt.sh

# Run comprehensive test
bash tests/skills/comprehensive-skill-activation-test.sh

# Test specific domain
bash tests/skills/comprehensive-skill-activation-test.sh | grep "=== DOMAIN: DEPLOYMENT"

Cache Management

# Rebuild cache (after skill changes)
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "test"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# Verify cache count
wc -l ~/.claude/cache/skill-index-hybrid.txt
# Expected: N+1 (header + N skills)

# Check cache health
bash scripts/cache-health-check.sh

Monitoring

# Weekly health check
bash scripts/weekly-skill-health-check.sh

# Analytics and trends
node scripts/skill-activation-analytics.js

# Coverage report
bash scripts/skill-coverage-report.sh

# System cleanup
bash scripts/skill-system-cleanup.sh

Skill Management

# Count total skills
find ~/.claude/skills -name "SKILL.md" -type f | wc -l

# List all skills
find ~/.claude/skills -name "SKILL.md" -type f | sed 's|.*/\([^/]*\)/SKILL.md|\1|'

# Find skill by keyword
grep -r "deployment" ~/.claude/skills/*/SKILL.md | cut -d: -f1 | sort -u

🔧 Troubleshooting

Issue 1: Cache Coverage Below 100%

Symptoms:

Cache shows fewer skills than filesystem
Skills exist but don’t match queries
Coverage <95%

Diagnosis:

FS_COUNT=$(find ~/.claude/skills -name "SKILL.md" -type f | wc -l)
CACHE_COUNT=$(( $(wc -l < ~/.claude/cache/skill-index-hybrid.txt) - 1 ))
echo "Filesystem: $FS_COUNT | Cache: $CACHE_COUNT"

Solution:

# Force cache rebuild
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "rebuild"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# Verify coverage now 100%

Prevention: Always rebuild cache after skill modifications.

Issue 2: Skill Not Ranking in Top 3

Symptoms:

Skill exists and in cache
But ranks #4-10 for relevant queries
Tests showing FAIL

Diagnosis:

# Test specific query
echo '{"prompt": "your query"}' | bash .claude/hooks/pre-prompt.sh

# Check ranking:
# ✅ other-skill-1 (rank #1)
# ✅ other-skill-2 (rank #2)
# ✅ other-skill-3 (rank #3)
# (your-skill is #4)

Solution:

# 1. Add exact query phrase to skill Triggers
vim ~/.claude/skills/your-skill/SKILL.md

# Add to Triggers: your query, query variations, related terms

# 2. Rebuild cache
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "test"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# 3. Re-test
echo '{"prompt": "your query"}' | bash .claude/hooks/pre-prompt.sh
# Expected: your-skill now in top 3

Best Practices:

Add 7-10 trigger keywords per skill
Include exact user query phrases
Use specific terms (not generic)
Test after every trigger update

Issue 3: Accuracy Dropped >5%

Symptoms:

Weekly test shows accuracy drop
Multiple domains affected
No obvious code changes

Diagnosis:

# Compare recent results
ls -t tests/skills/results/skill-test-*.json | head -3

# Check differences
diff <(cat result1.json | grep FAIL) <(cat result2.json | grep FAIL)

Common Causes:

Cache staleness (most common)
Skill deletions (removed without updating tests)
Trigger keyword conflicts (new skill shadowing old)
Test suite changes (new harder tests added)

Solution:

# 1. Rebuild cache
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "rebuild"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# 2. Re-run test
bash tests/skills/comprehensive-skill-activation-test.sh

# 3. If still failing, analyze specific failures:
cat tests/skills/results/skill-test-*.json | grep '"status":"FAIL"' | jq -r '.expected + " | " + .query'

# 4. Update trigger keywords for recurring failures

Issue 4: Hook Not Running

Symptoms:

No skill suggestions appear
Hook output not showing
Claude not loading skills

Diagnosis:

# 1. Check hook exists
ls -la .claude/hooks/pre-prompt.sh

# 2. Check executable
test -x .claude/hooks/pre-prompt.sh && echo "Executable" || echo "Not executable"

# 3. Test manually
echo '{"prompt": "test"}' | bash .claude/hooks/pre-prompt.sh

Solution:

# Make hook executable
chmod +x .claude/hooks/pre-prompt.sh

# Test again
echo '{"prompt": "test"}' | bash .claude/hooks/pre-prompt.sh
# Expected: ✅ skill suggestions appear

Issue 5: Flaky Tests (Pass/Fail Inconsistently)

Symptoms:

Test passes sometimes, fails other times
Same query, different results
Accuracy varies >3% between runs

Diagnosis:

# Run test 5 times, check variance
for i in {1..5}; do
  bash tests/skills/comprehensive-skill-activation-test.sh > /tmp/run-$i.txt
  PASS=$(grep -c "^PASS:" /tmp/run-$i.txt)
  TOTAL=$(grep -c -E "^(PASS|FAIL):" /tmp/run-$i.txt)
  ACCURACY=$(awk "BEGIN {printf \"%.1f\", ($PASS / $TOTAL) * 100}")
  echo "Run $i: $ACCURACY%"
done

# Expected: All runs within 3% of each other
# If variance >3%: Flaky test issue

Common Causes:

Tied scores (multiple skills same score)
Cache rebuilding during test (timing issue)
Non-deterministic ranking (random tiebreaker)

Solution:

# 1. Ensure cache built before test
rm ~/.claude/cache/skill-index-hybrid.txt
echo '{"prompt": "rebuild"}' | bash .claude/hooks/pre-prompt.sh >/dev/null 2>&1

# 2. Run test (cache now stable)
bash tests/skills/comprehensive-skill-activation-test.sh

# 3. For tied scores, increase trigger specificity
#    (add more keywords to preferred skill)

📚 Additional Resources

Production Implementation

Repository: https://github.com/ytrofr/production
Branch: dev-Knowledge
Entry #271: Option A Complete (88.2% accuracy)
Entry #272: Sustainability Infrastructure (85+ hours/year ROI)
Entry #267: 370x Performance Optimization

Skill Activation System Overview - Architecture and results
Quick Start Guide - Getting started with Claude Code

External Resources

Anthropic Official Docs: Claude Code best practices
Sionic AI Research: Skill activation patterns (84% improvement)

🎯 Success Criteria

Immediate (Day 1)

✅ Hook script created and executable
✅ At least 5 skills created
✅ Cache built and verified
✅ First test runs successfully

Short-term (Week 1)

✅ 20+ skills created across domains
✅ Test suite with 50+ queries
✅ Accuracy >70%
✅ Weekly health check scheduled

Long-term (Month 1)

✅ 50+ skills covering major domains
✅ Test suite with 100+ queries
✅ Accuracy >85%
✅ Weekly monitoring operational
✅ Monthly optimization workflow established

Excellence (Quarter 1)

✅ 100+ skills comprehensive coverage
✅ Test suite with 150+ queries
✅ Accuracy >88%
✅ Perfect domains (100%) established
✅ ROI tracking (hours saved)

📝 Implementation Checklist

Use this checklist to track your implementation:

Setup Phase

Create .claude/hooks/pre-prompt.sh
Make hook executable (chmod +x)
Create ~/.claude/skills/ directory
Create ~/.claude/cache/ directory
Create tests/skills/results/ directory

First Skills

Create 5 core skills (deployment, database, api, testing, troubleshooting)
Each skill has YAML frontmatter with Triggers
Each skill has “Use when…” in description
Each skill <500 lines

Testing

Create test script tests/skills/comprehensive-skill-activation-test.sh
Add test queries for each skill (5+ per skill)
Run first test suite
Verify accuracy >50%

Optimization

Optimize trigger keywords (add exact query phrases)
Rebuild cache after updates
Re-test and verify improvement
Target accuracy >70%

Monitoring

Create scripts/weekly-skill-health-check.sh
Schedule weekly checks (Monday 9AM)
Create scripts/cache-health-check.sh
Document baseline metrics

Sustainability

Create quality rules in .claude/rules/skills/
Set up cache rebuild reminders
Document trigger optimization workflow
Establish monthly review process

Advanced

🚀 Next Steps

Start with 5 skills: Deployment, Database, API, Testing, Troubleshooting
Create 25 test queries: 5 per skill
Run first test: Target 70% accuracy
Iterate: Add triggers, rebuild cache, re-test
Expand: Add more skills gradually
Monitor: Weekly health checks
Optimize: Monthly trigger reviews
Scale: 50+ skills, 100+ tests, 85%+ accuracy

Questions?

Check Troubleshooting section
Review Production implementation (dev-Knowledge branch)
Reference Entry #271 and #272 for detailed patterns

Ready to start? Follow the Step-by-Step Setup and begin with your first 5 skills!

Last Updated: 2026-01-15
Author: Production dev-Knowledge Branch
Status: Production-validated, battle-tested
Accuracy: 88.2% (150/170 tests)
Performance: 370x optimization (50s → 136ms)
ROI: 85+ hours/year saved

Pre-Prompt Hook System - Complete Implementation Guide

📋 Table of Contents

🎯 What is the Pre-Prompt Hook?

Before/After Comparison

🏗️ Architecture Overview

Performance Metrics

🚀 Step-by-Step Setup

Step 1: Create Hook Script

Step 2: Create Skill Directory Structure

Step 3: Create Your First Skill

When to Use

Core Patterns

Pre-Deployment Checklist

Deployment Commands

Post-Deployment Validation

Related Skills

Step 5: Create Test Suite

Step 6: Run First Test

🚨 Critical Cache Management

The Cache Staleness Problem (Entry #271 Discovery)

Solution: Manual Cache Rebuild (MANDATORY)

When to Rebuild Cache

Cache Health Check Script

🎯 Test Priority System

Priority Levels (Entry #271 Standard)

Test Format

Example Test Suite Structure

Production Results (170 tests)

🔑 Trigger Optimization

5 Core Principles (Entry #271 Patterns)

1. Use Exact User Query Phrases

2. Include Command Variations

3. Add Action + Object Patterns

4. Natural Language Variations

5. Avoid Generic Terms

Trigger Optimization Workflow

Recommended Trigger Count

📊 Weekly Monitoring (Entry #272)

Setup Weekly Health Check

Schedule Weekly Checks

Weekly Checklist (10 minutes)

Monthly Optimization (1st Monday, 30 minutes)

ROI Analysis

📊 Domain Performance

Production Results (170 tests across 12 domains)

How to Improve Domain Performance

⚡ Quick Commands

Testing

Cache Management

Monitoring

Skill Management

🔧 Troubleshooting

Issue 1: Cache Coverage Below 100%

Issue 2: Skill Not Ranking in Top 3

Issue 3: Accuracy Dropped >5%

Issue 4: Hook Not Running

Issue 5: Flaky Tests (Pass/Fail Inconsistently)

📚 Additional Resources

Production Implementation

Related Documentation

External Resources

🎯 Success Criteria

Immediate (Day 1)

Short-term (Week 1)

Long-term (Month 1)

Excellence (Quarter 1)

📝 Implementation Checklist

Setup Phase

First Skills

Testing

Optimization

Monitoring

Sustainability

Advanced

🚀 Next Steps