Trigger Types - Complete Guide

Complete reference for configuring skill triggers in Claude Code's skill auto-activation system.

Table of Contents

• Keyword Triggers (Explicit)
• Intent Pattern Triggers (Implicit)
• File Path Triggers
• Content Pattern Triggers
• Best Practices Summary

Keyword Triggers (Explicit)

How It Works

Case-insensitive substring matching in user's prompt.

Use For

Topic-based activation where user explicitly mentions the subject.

Configuration

"promptTriggers": {
  "keywords": ["layout", "grid", "toolbar", "submission"]
}

Example

• User prompt: "how does the layout system work?"
• Matches: "layout" keyword
• Activates: project-catalog-developer

Best Practices

• Use specific, unambiguous terms
• Include common variations ("layout", "layout system", "grid layout")
• Avoid overly generic words ("system", "work", "create")
• Test with real prompts

Intent Pattern Triggers (Implicit)

How It Works

Regex pattern matching to detect user's intent even when they don't mention the topic explicitly.

Use For

Action-based activation where user describes what they want to do rather than the specific topic.

Configuration

"promptTriggers": {
  "intentPatterns": [
    "(create|add|implement).*?(feature|endpoint)",
    "(how does|explain).*?(layout|workflow)"
  ]
}

Examples

Database Work:

• User prompt: "add user tracking feature"
• Matches: (add).*?(feature)
• Activates: database-verification, error-tracking

Component Creation:

• User prompt: "create a dashboard widget"
• Matches: (create).*?(component) (if component in pattern)
• Activates: frontend-dev-guidelines

Best Practices

• Capture common action verbs: (create|add|modify|build|implement)
• Include domain-specific nouns: (feature|endpoint|component|workflow)
• Use non-greedy matching: .*? instead of .*
• Test patterns thoroughly with regex tester (https://regex101.com/)
• Don't make patterns too broad (causes false positives)
• Don't make patterns too specific (causes false negatives)

Common Pattern Examples

# Database Work
(add|create|implement).*?(user|login|auth|feature)

# Explanations
(how does|explain|what is|describe).*?

# Frontend Work
(create|add|make|build).*?(component|UI|page|modal|dialog)

# Error Handling
(fix|handle|catch|debug).*?(error|exception|bug)

# Workflow Operations
(create|add|modify).*?(workflow|step|branch|condition)

File Path Triggers

How It Works

Glob pattern matching against the file path being edited.

Use For

Domain/area-specific activation based on file location in the project.

Configuration

"fileTriggers": {
  "pathPatterns": [
    "frontend/src/**/*.tsx",
    "form/src/**/*.ts"
  ],
  "pathExclusions": [
    "**/*.test.ts",
    "**/*.spec.ts"
  ]
}

Glob Pattern Syntax

• ** = Any number of directories (including zero)
• * = Any characters within a directory name
• Examples:
  • frontend/src/**/*.tsx = All .tsx files in frontend/src and subdirs
  • **/schema.prisma = schema.prisma anywhere in project
  • form/src/**/*.ts = All .ts files in form/src subdirs

Example

• File being edited: frontend/src/components/Dashboard.tsx
• Matches: frontend/src/**/*.tsx
• Activates: frontend-dev-guidelines

Best Practices

• Be specific to avoid false positives
• Use exclusions for test files: **/*.test.ts
• Consider subdirectory structure
• Test patterns with actual file paths
• Use narrower patterns when possible: form/src/services/** not form/**

Common Path Patterns

# Frontend
frontend/src/**/*.tsx        # All React components
frontend/src/**/*.ts         # All TypeScript files
frontend/src/components/**   # Only components directory

# Backend Services
form/src/**/*.ts            # Form service
email/src/**/*.ts           # Email service
users/src/**/*.ts           # Users service

# Database
**/schema.prisma            # Prisma schema (anywhere)
**/migrations/**/*.sql      # Migration files
database/src/**/*.ts        # Database scripts

# Workflows
form/src/workflow/**/*.ts              # Workflow engine
form/src/workflow-definitions/**/*.json # Workflow definitions

# Test Exclusions
**/*.test.ts                # TypeScript tests
**/*.test.tsx               # React component tests
**/*.spec.ts                # Spec files

Content Pattern Triggers

How It Works

Regex pattern matching against the file's actual content (what's inside the file).

Use For

Technology-specific activation based on what the code imports or uses (Prisma, controllers, specific libraries).

Configuration

"fileTriggers": {
  "contentPatterns": [
    "import.*[Pp]risma",
    "PrismaService",
    "\\.findMany\\(",
    "\\.create\\("
  ]
}

Examples

Prisma Detection:

• File contains: import { PrismaService } from '@project/database'
• Matches: import.*[Pp]risma
• Activates: database-verification

Controller Detection:

• File contains: export class UserController {
• Matches: export class.*Controller
• Activates: error-tracking

Best Practices

• Match imports: import.*[Pp]risma (case-insensitive with [Pp])
• Escape special regex chars: \\.findMany\\( not .findMany(
• Patterns use case-insensitive flag
• Test against real file content
• Make patterns specific enough to avoid false matches

Common Content Patterns

# Prisma/Database
import.*[Pp]risma                # Prisma imports
PrismaService                    # PrismaService usage
prisma\.                         # prisma.something
\.findMany\(                     # Prisma query methods
\.create\(
\.update\(
\.delete\(

# Controllers/Routes
export class.*Controller         # Controller classes
router\.                         # Express router
app\.(get|post|put|delete|patch) # Express app routes

# Error Handling
try\s*\{                        # Try blocks
catch\s*\(                      # Catch blocks
throw new                        # Throw statements

# React/Components
export.*React\.FC               # React functional components
export default function.*       # Default function exports
useState|useEffect              # React hooks

Best Practices Summary

DO:

✅ Use specific, unambiguous keywords ✅ Test all patterns with real examples ✅ Include common variations ✅ Use non-greedy regex: .*? ✅ Escape special characters in content patterns ✅ Add exclusions for test files ✅ Make file path patterns narrow and specific

DON'T:

❌ Use overly generic keywords ("system", "work") ❌ Make intent patterns too broad (false positives) ❌ Make patterns too specific (false negatives) ❌ Forget to test with regex tester (https://regex101.com/) ❌ Use greedy regex: .* instead of .*? ❌ Match too broadly in file paths

Testing Your Triggers

Test keyword/intent triggers:

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

Test file path/content triggers:

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{
  "session_id": "test",
  "tool_name": "Edit",
  "tool_input": {"file_path": "/path/to/test/file.ts"}
}
EOF

Related Files:

• SKILL.md - Main skill guide
• SKILL_RULES_REFERENCE.md - Complete skill-rules.json schema
• PATTERNS_LIBRARY.md - Ready-to-use pattern library