Troubleshooting - Skill Activation Issues

Complete debugging guide for skill activation problems.

Skill Not Triggering
- UserPromptSubmit Not Suggesting
- PreToolUse Not Blocking
False Positives
Hook Not Executing
Performance Issues

Skill Not Triggering

UserPromptSubmit Not Suggesting

Symptoms: Ask a question, but no skill suggestion appears in output.

Common Causes:

1. Keywords Don't Match

Check:

Look at promptTriggers.keywords in skill-rules.json
Are the keywords actually in your prompt?
Remember: case-insensitive substring matching

Example:

"keywords": ["layout", "grid"]

"how does the layout work?" → ✅ Matches "layout"
"how does the grid system work?" → ✅ Matches "grid"
"how do layouts work?" → ✅ Matches "layout"
"how does it work?" → ❌ No match

Fix: Add more keyword variations to skill-rules.json

2. Intent Patterns Too Specific

Check:

Look at promptTriggers.intentPatterns
Test regex at https://regex101.com/
May need broader patterns

Example:

"intentPatterns": [
  "(create|add).*?(database.*?table)"  // Too specific
]

"create a database table" → ✅ Matches
"add new table" → ❌ Doesn't match (missing "database")

Fix: Broaden the pattern:

"intentPatterns": [
  "(create|add).*?(table|database)"  // Better
]

3. Typo in Skill Name

Check:

Skill name in SKILL.md frontmatter
Skill name in skill-rules.json
Must match exactly

Example:

# SKILL.md
name: project-catalog-developer

// skill-rules.json
"project-catalogue-developer": {  // ❌ Typo: catalogue vs catalog
  ...
}

Fix: Make names match exactly

4. JSON Syntax Error

Check:

cat .claude/skills/skill-rules.json | jq .

If invalid JSON, jq will show the error.

Common errors:

Trailing commas
Missing quotes
Single quotes instead of double
Unescaped characters in strings

Fix: Correct JSON syntax, validate with jq

Debug Command

Test the hook manually:

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

Expected: Your skill should appear in the output.

PreToolUse Not Blocking

Symptoms: Edit a file that should trigger a guardrail, but no block occurs.

Common Causes:

1. File Path Doesn't Match Patterns

Check:

File path being edited
fileTriggers.pathPatterns in skill-rules.json
Glob pattern syntax

Example:

"pathPatterns": [
  "frontend/src/**/*.tsx"
]

Editing: frontend/src/components/Dashboard.tsx → ✅ Matches
Editing: frontend/tests/Dashboard.test.tsx → ✅ Matches (add exclusion!)
Editing: backend/src/app.ts → ❌ Doesn't match

Fix: Adjust glob patterns or add the missing path

2. Excluded by pathExclusions

Check:

Are you editing a test file?
Look at fileTriggers.pathExclusions

Example:

"pathExclusions": [
  "**/*.test.ts",
  "**/*.spec.ts"
]

Editing: services/user.test.ts → ❌ Excluded
Editing: services/user.ts → ✅ Not excluded

Fix: If test exclusion too broad, narrow it or remove

3. Content Pattern Not Found

Check:

Does the file actually contain the pattern?
Look at fileTriggers.contentPatterns
Is the regex correct?

Example:

"contentPatterns": [
  "import.*[Pp]risma"
]

File has: import { PrismaService } from './prisma' → ✅ Matches
File has: import { Database } from './db' → ❌ Doesn't match

Debug:

# Check if pattern exists in file
grep -i "prisma" path/to/file.ts

Fix: Adjust content patterns or add missing imports

4. Session Already Used Skill

Check session state:

ls .claude/hooks/state/
cat .claude/hooks/state/skills-used-{session-id}.json

Example:

{
  "skills_used": ["database-verification"],
  "files_verified": []
}

If the skill is in skills_used, it won't block again in this session.

Fix: Delete the state file to reset:

rm .claude/hooks/state/skills-used-{session-id}.json

5. File Marker Present

Check file for skip marker:

grep "@skip-validation" path/to/file.ts

If found, the file is permanently skipped.

Fix: Remove the marker if verification is needed again

6. Environment Variable Override

Check:

echo $SKIP_DB_VERIFICATION
echo $SKIP_SKILL_GUARDRAILS

If set, the skill is disabled.

Fix: Unset the environment variable:

unset SKIP_DB_VERIFICATION

Debug Command

Test the hook manually:

cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts 2>&1
{
  "session_id": "debug",
  "tool_name": "Edit",
  "tool_input": {"file_path": "/root/git/your-project/form/src/services/user.ts"}
}
EOF
echo "Exit code: $?"

Expected:

Exit code 2 + stderr message if should block
Exit code 0 + no output if should allow

False Positives

Symptoms: Skill triggers when it shouldn't.

Common Causes & Solutions:

1. Keywords Too Generic

Problem:

"keywords": ["user", "system", "create"]  // Too broad

Triggers on: "user manual", "file system", "create directory"

Solution: Make keywords more specific

"keywords": [
  "user authentication",
  "user tracking",
  "create feature"
]

2. Intent Patterns Too Broad

Problem:

"intentPatterns": [
  "(create)"  // Matches everything with "create"
]

Triggers on: "create file", "create folder", "create account"

Solution: Add context to patterns

"intentPatterns": [
  "(create|add).*?(database|table|feature)"  // More specific
]

Advanced: Use negative lookaheads to exclude

(create)(?!.*test).*?(feature)  // Don't match if "test" appears

3. File Paths Too Generic

Problem:

"pathPatterns": [
  "form/**"  // Matches everything in form/
]

Triggers on: test files, config files, everything

Solution: Use narrower patterns

"pathPatterns": [
  "form/src/services/**/*.ts",  // Only service files
  "form/src/controllers/**/*.ts"
]

4. Content Patterns Catching Unrelated Code

Problem:

"contentPatterns": [
  "Prisma"  // Matches in comments, strings, etc.
]

Triggers on: // Don't use Prisma here
Triggers on: const note = "Prisma is cool"

Solution: Make patterns more specific

"contentPatterns": [
  "import.*[Pp]risma",        // Only imports
  "PrismaService\\.",         // Only actual usage
  "prisma\\.(findMany|create)" // Specific methods
]

5. Adjust Enforcement Level

Last resort: If false positives are frequent:

{
  "enforcement": "block"  // Change to "suggest"
}

This makes it advisory instead of blocking.

Hook Not Executing

Symptoms: Hook doesn't run at all - no suggestion, no block.

Common Causes:

1. Hook Not Registered

Check .claude/settings.json:

cat .claude/settings.json | jq '.hooks.UserPromptSubmit'
cat .claude/settings.json | jq '.hooks.PreToolUse'

Expected: Hook entries present

Fix: Add missing hook registration:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"
          }
        ]
      }
    ]
  }
}

2. Bash Wrapper Not Executable

Check:

ls -l .claude/hooks/*.sh

Expected: -rwxr-xr-x (executable)

Fix:

chmod +x .claude/hooks/*.sh

3. Incorrect Shebang

Check:

head -1 .claude/hooks/skill-activation-prompt.sh

Expected: #!/bin/bash

Fix: Add correct shebang to first line

4. npx/tsx Not Available

Check:

npx tsx --version

Expected: Version number

Fix: Install dependencies:

cd .claude/hooks
npm install

5. TypeScript Compilation Error

Check:

cd .claude/hooks
npx tsc --noEmit skill-activation-prompt.ts

Expected: No output (no errors)

Fix: Correct TypeScript syntax errors

Performance Issues

Symptoms: Hooks are slow, noticeable delay before prompt/edit.

Common Causes:

1. Too Many Patterns

Check:

Count patterns in skill-rules.json
Each pattern = regex compilation + matching

Solution: Reduce patterns

Combine similar patterns
Remove redundant patterns
Use more specific patterns (faster matching)

2. Complex Regex

Problem:

(create|add|modify|update|implement|build).*?(feature|endpoint|route|service|controller|component|UI|page)

Long alternations = slow

Solution: Simplify

(create|add).*?(feature|endpoint)  // Fewer alternatives

3. Too Many Files Checked

Problem:

"pathPatterns": [
  "**/*.ts"  // Checks ALL TypeScript files
]

Solution: Be more specific

"pathPatterns": [
  "form/src/services/**/*.ts",  // Only specific directory
  "form/src/controllers/**/*.ts"
]

4. Large Files

Content pattern matching reads entire file - slow for large files.

Solution:

Only use content patterns when necessary
Consider file size limits (future enhancement)

Measure Performance

# UserPromptSubmit
time echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts

# PreToolUse
time cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

Target metrics:

UserPromptSubmit: < 100ms
PreToolUse: < 200ms

Related Files:

SKILL.md - Main skill guide
HOOK_MECHANISMS.md - How hooks work
SKILL_RULES_REFERENCE.md - Configuration reference

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting - Skill Activation Issues

Table of Contents

Skill Not Triggering

UserPromptSubmit Not Suggesting

1. Keywords Don't Match

2. Intent Patterns Too Specific

3. Typo in Skill Name

4. JSON Syntax Error

Debug Command

PreToolUse Not Blocking

1. File Path Doesn't Match Patterns

2. Excluded by pathExclusions

3. Content Pattern Not Found

4. Session Already Used Skill

5. File Marker Present

6. Environment Variable Override

Debug Command

False Positives

1. Keywords Too Generic

2. Intent Patterns Too Broad

3. File Paths Too Generic

4. Content Patterns Catching Unrelated Code

5. Adjust Enforcement Level

Hook Not Executing

1. Hook Not Registered

2. Bash Wrapper Not Executable

3. Incorrect Shebang

4. npx/tsx Not Available

5. TypeScript Compilation Error

Performance Issues

1. Too Many Patterns

2. Complex Regex

3. Too Many Files Checked

4. Large Files

Measure Performance

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting - Skill Activation Issues

Table of Contents

Skill Not Triggering

UserPromptSubmit Not Suggesting

1. Keywords Don't Match

2. Intent Patterns Too Specific

3. Typo in Skill Name

4. JSON Syntax Error

Debug Command

PreToolUse Not Blocking

1. File Path Doesn't Match Patterns

2. Excluded by pathExclusions

3. Content Pattern Not Found

4. Session Already Used Skill

5. File Marker Present

6. Environment Variable Override

Debug Command

False Positives

1. Keywords Too Generic

2. Intent Patterns Too Broad

3. File Paths Too Generic

4. Content Patterns Catching Unrelated Code

5. Adjust Enforcement Level

Hook Not Executing

1. Hook Not Registered

2. Bash Wrapper Not Executable

3. Incorrect Shebang

4. npx/tsx Not Available

5. TypeScript Compilation Error

Performance Issues

1. Too Many Patterns

2. Complex Regex

3. Too Many Files Checked

4. Large Files

Measure Performance