Pre Prompt Hook Complete Guide

---
layout: default
title: "Claude Code Pre-Prompt Hook - 370x Performance Optimization"
description: "Optimize Claude Code pre-prompt hooks from 38 seconds to 103ms. Skill caching, hybrid matching, and branch-aware context injection."
---

> **ARCHIVED**: This chapter documents the custom pre-prompt hook skill matching system, which was superseded by Claude Code's native skill loading (v2.1.76+). Kept for historical reference only. See [Skills Activation System](/docs/skill-activation-system) for the current approach.

# 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

---

## 📋 Table of Contents

1. [What is the Pre-Prompt Hook?](#what-is-the-pre-prompt-hook)
2. [Architecture Overview](#architecture-overview)
3. [Step-by-Step Setup](#step-by-step-setup)
4. [Critical Cache Management](#critical-cache-management)
5. [Test Priority System](#test-priority-system)
6. [Trigger Optimization](#trigger-optimization)
7. [Weekly Monitoring](#weekly-monitoring)
8. [Domain Performance](#domain-performance)
9. [Quick Commands](#quick-commands)
10. [Troubleshooting](#troubleshooting)

---

## 🎯 What is the Pre-Prompt Hook?

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

1. **Intercepts** your query before Claude sees it
2. **Matches** against your skills library using keyword scoring
3. **Ranks** skills by relevance (scoring algorithm)
4. **Injects** top 3 matched skills into Claude's context
5. **Provides** proactive recommendations

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

### Before/After Comparison