Claude Skills Supercharged

AI-powered skill auto-injection system for Claude Code
Skills

Stop manually invoking skills. Let AI detect what you need and inject it
automatically with 95%+ accuracy. The system analyzes your prompts using Claude
Haiku 4.5, assigns confidence scores, and intelligently loads the right
context—every time.

💡 Credit: Base reference architecture from
@diet103's
claude-code-infrastructure-showcase

---

📊 Performance at a Glance

Metric	Value
✅ Test Coverage	120/120 tests passing
⚡ Response Time	<10ms (cached) / ~200ms (first call)
💰 Monthly Cost	$1-2 @ 100 prompts/day
🎯 Accuracy	95%+ skill detection rate

---

🎯 Why This?

The Problem: Manually loading skills is tedious, error-prone, and breaks
your flow. You forget which skills exist, waste time invoking them, and lose
context between conversations.

The Solution: This system uses AI to automatically:

• 🔍 Analyze your prompt intent with Claude Haiku 4.5
• 📊 Score each skill's relevance (0.0-1.0 confidence)
• 🚀 Inject high-confidence skills (>0.65) into context automatically
• 💾 Cache results for 1 hour to reduce costs
• 🔗 Track loaded skills per session (no duplicates)

Before: "Let me manually load python-best-practices... wait, was it
python-style? Let me check..."

After: Just say "help me write Python code" and the right skills load
automatically. 🎉

---

📑 Table of Contents

• Features
• Quick Start
• How It Works
• Included Skills
• Architecture
• Creating Custom Skills
• Keeping Skills Updated
• Configuration
• Testing
• Troubleshooting
• Documentation
• FAQ

---

✨ Features

• 🤖 AI-Powered Intent Analysis — Claude Haiku 4.5 analyzes your prompts to
  detect relevant skills with 0.0-1.0 confidence scoring
• ⚡ Automatic Injection — High-confidence skills (>0.65) automatically
  loaded into context
• 💾 Smart Caching — 1-hour TTL reduces API costs (~$1-2/month) and improves
  response time (<10ms cached)
• 🔄 Session Tracking — Skills only injected once per conversation, no
  duplicates
• 🔗 Bidirectional Affinity — Related skills automatically loaded together
• 📚 Progressive Disclosure — Main skill files under 500 lines, detailed
  content in resources
• 🛡️ Guardrail Skills — Enforce critical best practices (e.g., API
  security, input validation)
• ✅ Comprehensive Testing — 120 tests with full coverage of the injection
  pipeline

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/jefflester/claude-skills-supercharged.git
cd claude-skills-supercharged

2. Install Dependencies

cd .claude/hooks
npm install

3. Configure API Key

cp .env.example .env
# Edit .env and add: ANTHROPIC_API_KEY=sk-ant-your-key-here

Get your API key from: https://console.anthropic.com/

4. Test the System

# Test skill activation
echo '{"session_id":"test","prompt":"I need to write Python code"}' | \
  npx tsx skill-activation-prompt.ts

5. (Optional) Set Up Pre-commit Hooks

# Install pre-commit
pip install pre-commit  # or: brew install pre-commit

# Install git hooks
pre-commit install

# Run on all files (optional)
pre-commit run --all-files

6. Use with Claude Code

The system automatically activates when you use Claude Code in this project. Try
these prompts:

• "Help me write a Python function" → Loads python-best-practices
• "I need to add a REST API endpoint" → Loads api-security
• "How do I write a good commit message?" → Loads git-workflow

You'll see a banner showing which skills were loaded:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 AUTO-LOADED SKILLS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

<skill name="python-best-practices">
[Skill content automatically injected...]
</skill>

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔧 How It Works

The skills system uses a 7-stage injection pipeline:

┌─────────────────────────────────────────────────────────────┐
│ 1.  User Prompt                                             │
│    "Help me write Python code"                              │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 2.  Intent Analysis                                         │
│    • AI Analysis (Claude Haiku 4.5)                         │
│    • Keyword Fallback (if API unavailable)                  │
│    • Cache Check (MD5 hash, 1-hour TTL)                     │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Confidence Scoring                                       │
│    python-best-practices: 0.92     Required (>0.65)         │
│    git-workflow: 0.58              Suggested (0.50-0.65)    │
│    api-security: 0.12              Ignored (<0.50)          │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 4.  Skill Filtration                                        │
│    • Remove already-loaded skills                           │
│    • Apply 2-skill injection limit                          │
│    • Promote suggested skills if slots available            │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 5.  Affinity Injection                                      │
│    • Load bidirectionally-related skills                    │
│    • Free of slot cost (bonus injections)                   │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 6.  Dependency Resolution                                   │
│    • Resolve requiredSkills dependencies                    │
│    • Sort by injectionOrder (0-100)                         │
│    • Detect circular dependencies                           │
└────────────────────┬────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│ 7.  Skill Injection & State Management                      │
│    • Read SKILL.md files                                    │
│    • Wrap in <skill> XML tags                               │
│    • Track loaded skills (prevent duplicates)               │
│    • Output enriched context to Claude                      │
└─────────────────────────────────────────────────────────────┘

Key Concepts

Intent Analysis: Claude Haiku 4.5 analyzes your prompt to determine what
you're trying to do, assigning confidence scores to each skill.

Confidence Thresholds:

• >0.65 - Required (automatically injected)
• 0.50-0.65 - Suggested (shown as optional)
• <0.50 - Ignored

Skill Types:

• Domain skills: Provide comprehensive guidance (e.g.,
  python-best-practices)
• Guardrail skills: Enforce critical practices (e.g., api-security)

Session Tracking: Skills are tracked per conversation. Once loaded, they
won't be injected again in the same conversation.

Caching: Intent analysis results are cached for 1 hour using MD5 hashing of
(prompt + skills config).

🎓 Included Skills

1. skill-developer

A domain skill that guides creation and management of the skills system.

Covers: Skill structure, triggers, hooks, 500-line rule, progressive
disclosure

2. python-best-practices (Domain)

Python development best practices.

Covers: PEP 8, type hints, NumPy docstrings, common patterns, testing

3. git-workflow (Domain)

Git workflow and version control best practices.

Covers: Conventional Commits, branching, PRs, common operations, security

4. api-security (Guardrail)

API security and vulnerability prevention. Enforces security checks.

Covers: Authentication, input validation, SQL injection, XSS, OWASP Top 10

🏗️ Architecture

The system is built on three main components:

1. Hook System (.claude/hooks/)

   • UserPromptSubmit hook that analyzes prompts
   • 13 TypeScript modules handling the injection pipeline
   • Comprehensive test suite (11 test files)

2. Skills (.claude/skills/)

   • SKILL.md files with YAML frontmatter
   • Resource directories for detailed content
   • skill-rules.json configuration

3. Configuration

   • skill-rules.json: Defines all skills and triggers
   • intent-analysis-prompt.txt: AI analysis template
   • .env: API key configuration

For detailed architecture documentation, see
docs/ARCHITECTURE.md.

🛠️ Creating Custom Skills

Creating a new skill is simple:

1. Create Skill Directory

mkdir -p .claude/skills/my-skill/resources

2. Create SKILL.md

---
name: my-skill
description: Brief description of what this skill does
---

# My Skill

## Purpose
What this skill helps with...

## When to Use This Skill
Wh