Skills Manager (Smart Router)

Purpose

Context-aware routing to skills and hooks management. Helps you troubleshoot, fine-tune, and manage the automated documentation system.

When Auto-Activated

Discussing skills activation or hooks
Creating new skills
Keywords: skill activation, hook, troubleshoot, fine-tune, keyword, skill-rules.json, create skill, new skill, agentskills
Debugging why a skill didn't activate or activated incorrectly

🚨 CRITICAL RULES

Logs are your friend - Always check .claude/logs/skill-activations.log first
Test after changes - Always verify modifications to skill-rules.json work
Validate JSON - Use jq to validate skill-rules.json before committing
Keywords should be specific - Too-broad keywords cause false positives

📋 Quick Diagnostic Workflow

Problem: Skill Didn't Activate

Check logs:

tail -20 .claude/logs/skill-activations.log

Check current keywords:

cat .claude/hooks/skill-rules.json | jq '.skills."SKILL-NAME".promptTriggers.keywords'

Add missing keyword:
- Ask Claude: "Add 'KEYWORD' to SKILL-NAME"
- Or edit .claude/hooks/skill-rules.json directly

Test:

echo '{"prompt":"test prompt"}' | .claude/hooks/skill-activation-prompt.sh

Problem: Skill Activated When Shouldn't

Identify the trigger - Check logs to see which keyword matched
Remove or make more specific:
- Remove: "Remove 'text' from localization-developer"
- Make specific: Replace "text" with "localized text"

Verify:

tail .claude/logs/skill-activations.log

🎯 Common Tasks

Add a Keyword

Quick: Ask Claude

"Add 'refactoring' to ios-dev-guidelines keywords"

Manual: Edit .claude/hooks/skill-rules.json

"keywords": [
  "swift",
  "refactoring"  // ← Add here
]

Remove a Keyword

Quick: Ask Claude

"Remove 'text' from localization-developer, it's too broad"

Manual: Edit and remove from keywords array

Check What Activated

tail -20 .claude/logs/skill-activations.log

Look for:

✓ Matched: skill-name     # ← This skill activated
No matches found          # ← Nothing activated

Test Activation Manually

echo '{"prompt":"add feature flag"}' | .claude/hooks/skill-activation-prompt.sh

Should output skill suggestion if match found.

Auto-Learning Feature

What it does: When a substantial prompt (100+ chars OR 3+ lines) doesn't activate any skills, the system prompts you with available skills and auto-updates keywords based on your feedback.

Workflow:

You submit a substantial prompt
No skills activate
System shows: "Should any of these skills be activated?"
You respond: "Yes, localization-developer should activate"
Claude extracts keywords from your prompt
Claude runs: .claude/hooks/utils/add-keywords-to-skill.sh localization-developer <keywords>
skill-rules.json updated
Future similar prompts auto-activate

Manual keyword extraction:

# Test keyword extraction
echo "Update space settings localization for membership tiers" | .claude/hooks/utils/extract-keywords.sh
# Output: membership, settings, localization, tiers, update

# Add keywords manually
.claude/hooks/utils/add-keywords-to-skill.sh localization-developer "membership" "tiers"

Logs:

Missed activations: .claude/logs/skill-activations-missed.log
Learning updates: .claude/logs/skill-learning.log

🔧 The System Components

Hooks (Automation)

Location: .claude/hooks/

What they do:

skill-activation-prompt.sh - Suggests skills based on your prompt
post-tool-use-tracker.sh - Tracks file edits
swiftformat-post-edit.sh - Auto-formats Swift files immediately after edit
notification-alert.sh - Sends macOS notifications when Claude needs input

Skills (Routers)

Location: .claude/skills/*/SKILL.md

The 7 skills:

ios-dev-guidelines - Swift/iOS patterns
localization-developer - Localization
code-generation-developer - Feature flags, make generate
design-system-developer - Icons, typography, colors
skills-manager - This skill (meta!)
code-review-developer - Code review standards
feature-toggle-developer - Feature toggle removal, cleanup detection

Configuration

Location: .claude/hooks/skill-rules.json

What it contains:

Keywords for each skill
Intent patterns (regex)
File path patterns
Priority settings

📊 Configuration Structure

{
  "skills": {
    "skill-name": {
      "type": "domain",
      "priority": "high",  // or "medium", "low"
      "description": "Smart router to...",
      "promptTriggers": {
        "keywords": ["keyword1", "keyword2"],
        "intentPatterns": ["(create|add).*?something"]
      },
      "fileTriggers": {
        "pathPatterns": ["**/*.swift"],
        "contentPatterns": ["SomePattern"]
      }
    }
  },
  "config": {
    "maxSkillsPerPrompt": 2,
    "logActivations": true
  }
}

📝 Creating New Skills (agentskills.io Spec)

Skills must follow the agentskills.io specification.

Required SKILL.md Format

Every skill must start with YAML frontmatter:

---
name: skill-name
description: What this skill does and when to use it (max 1024 chars).
---

# Skill Title

## Purpose
...

Name Field Rules

1-64 characters
Lowercase only: a-z, 0-9, -
No start/end hyphens: skill-name ✅, -skill- ❌
No consecutive hyphens: my-skill ✅, my--skill ❌
Must match directory name: skills/my-skill/SKILL.md → name: my-skill

Description Field

1-1024 characters
Must describe: What it does AND when to use it
Include keywords that help agents identify relevant tasks

Good example:

description: Context-aware routing to the iOS localization system. Use when working with .xcstrings files, Loc constants, or user-facing text.

Optional Frontmatter Fields

---
name: skill-name
description: Required description.
license: MIT
compatibility: Designed for Claude Code
metadata:
  author: anytype
  version: "1.0"
---

Directory Structure

skill-name/
├── SKILL.md          # Required - main skill file
├── scripts/          # Optional - executable scripts
├── references/       # Optional - additional docs
└── assets/           # Optional - templates, images

Quick Checklist for New Skills

Directory name matches name field
YAML frontmatter with name and description
Name is lowercase with hyphens only
Description explains what AND when
SKILL.md under 500 lines (use references/ for details)
Added to skill-rules.json with keywords
Tested activation with sample prompts

⚠️ Common Issues

Hook Not Executing

Symptom: No activation messages, empty logs

Fix:

# Make hooks executable
chmod +x .claude/hooks/*.sh

# Verify
ls -l .claude/hooks/*.sh  # Should show rwx

Invalid JSON

Symptom: Hook fails silently

Fix:

# Validate
jq . .claude/hooks/skill-rules.json

# If error, ask Claude to fix it

Too Many False Positives

Symptom: Skill activates too often

Fix: Make keywords more specific

❌ "text" → activates for everything
✅ "localized text" → more specific

📚 Complete Documentation

Full Guide: .claude/SKILLS_MANAGEMENT_GUIDE.md

For comprehensive coverage of:

Detailed troubleshooting workflows
Advanced regex patterns for intent matching
Creating new skills from scratch
Monitoring and maintenance
Log rotation and cleanup
Complete skill-rules.json reference
Examples for every scenario

✅ Health Check Commands

# Check hook permissions
ls -l .claude/hooks/*.sh

# Validate configuration
jq . .claude/hooks/skill-rules.json

# View recent activations
tail -20 .claude/logs/skill-activations.log

# Count activations by skill
grep "Matched:" .claude/logs/skill-activations.log | sort | uniq -c

# Test specific prompt
echo '{"prompt":"your test"}' | .claude/hooks/skill-activation-prompt.sh

💡 Pro Tips

Ask Claude to check logs - "Check the logs for my last prompt"
Use logs for tuning - Review regularly to spot patterns
Start broad - Add broad keywords, narrow if too many false positives
Test everything - Always test after modifying skill-rules.json
Document changes - Add comments in skill-rules.json

🔗 Related Docs

.claude/hooks/README.md - Complete hooks documentation
.claude/skills/README.md - Skills system overview
CLAUDE.md - Main documentation

Navigation: This is a smart router. For deep troubleshooting and management details, always refer to SKILLS_MANAGEMENT_GUIDE.md.

Quick help: Just ask "Check skills system health" or "Why didn't X skill activate?"

skills-manager