skill-developer

# Skill Developer Guide ## Purpose Comprehensive guide for creating and managing skills in Claude Code with auto-activation system, following Anthropic's official best practices including the 500-line rule and progressive disclosure pattern. ## When to Use This Skill Automatically activates when you mention: - Creating or adding skills - Modifying skill triggers or rules - Understanding how skill activation works - Debugging skill activation issues - Working with skill-rules.json - Hook system mechanics - Claude Code best practices - Progressive disclosure - YAML frontmatter - 500-line rule --- ## System Overview ### Two-Hook Architecture **1. UserPromptSubmit Hook** (Proactive Suggestions) - **File**: `.claude/hooks/skill-activation-prompt.ts` - **Trigger**: BEFORE Claude sees user's prompt - **Purpose**: Suggest relevant skills based on keywords + intent patterns - **Method**: Injects formatted reminder as context (stdout → Claude's input) - **Use Cases**: Topic-based skills, implicit work detection **2. Stop Hook - Error Handling Reminder** (Gentle Reminders) - **File**: `.claude/hooks/error-handling-reminder.ts` - **Trigger**: AFTER Claude finishes responding - **Purpose**: Gentle reminder to self-assess error handling in code written - **Method**: Analyzes edited files for risky patterns, displays reminder if needed - **Use Cases**: Error handling awareness without blocking friction **Philosophy Change (2025-10-27):** We moved away from blocking PreToolUse for Sentry/error handling. Instead, use gentle post-response reminders that don't block workflow but maintain code quality awareness. ### Configuration File **Location**: `.claude/skills/skill-rules.json` Defines: - All skills and their trigger conditions - Enforcement levels (block, suggest, warn) - File path patterns (glob) - Content detection patterns (regex) - Skip conditions (session tracking, file markers, env vars) --- ## Skill Types ### 1. Guardrail Skills **Purpose:** Enforce critical best practices that prevent errors **Characteristics:** - Type: `"guardrail"` - Enforcement: `"block"` - Priority: `"critical"` or `"high"` - Block file edits until skill used - Prevent common mistakes (column names, critical errors) - Session-aware (don't repeat nag in same session) **Examples:** - `database-verification` - Verify table/column names before Prisma queries - `frontend-dev-guidelines` - Enforce React/TypeScript patterns **When to Use:** - Mistakes that cause runtime errors - Data integrity concerns - Critical compatibility issues ### 2. Domain Skills **Purpose:** Provide comprehensive guidance for specific areas **Characteristics:** - Type: `"domain"` - Enforcement: `"suggest"` - Priority: `"high"` or `"medium"` - Advisory, not mandatory - Topic or domain-specific - Comprehensive documentation **Examples:** - `backend-dev-guidelines` - Node.js/Express/TypeScript patterns - `frontend-dev-guidelines` - React/TypeScript best practices - `error-tracking` - Sentry integration guidance **When to Use:** - Complex systems requiring deep knowledge - Best practices documentation - Architectural patterns - How-to guides --- ## Quick Start: Creating a New Skill ### Step 1: Create Skill File **Location:** `.claude/skills/{skill-name}/SKILL.md` **Template:** ```markdown --- name: my-new-skill description: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms. --- # My New Skill ## Purpose What this skill helps with ## When to Use Specific scenarios and conditions ## Key Information The actual guidance, documentation, patterns, examples ``` **Best Practices:** - ✅ **Name**: Lowercase, hyphens, gerund form (verb + -ing) preferred - ✅ **Description**: Include ALL trigger keywords/phrases (max 1024 chars) - ✅ **Content**: Under 500 lines - use reference files for details - ✅ **Examples**: Real code examples - ✅ **Structure**: Clear headings, lists, code blocks ### Step 2: Add to skill-rules.json See [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) for complete schema. **Basic Template:** ```json { "my-new-skill": { "type": "domain", "enforcement": "suggest", "priority": "medium", "promptTriggers": { "keywords": ["keyword1", "keyword2"], "intentPatterns": ["(create|add).*?something"] } } } ``` ### Step 3: Test Triggers **Test UserPromptSubmit:** ```bash echo '{"session_id":"test","prompt":"your test prompt"}' | \ npx tsx .claude/hooks/skill-activation-prompt.ts ``` **Test PreToolUse:** ```bash cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts {"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}} EOF ``` ### Step 4: Refine Patterns Based on testing: - Add missing keywords - Refine intent patterns to reduce false positives - Adjust file path patterns - Test content patterns against actual files ### Step 5: Follow Anthropic Best Practices ✅ Keep SKILL.md under 500 lines ✅ Use progressive disclosure with reference files ✅ Add table of contents to reference files > 100 lines ✅ Write detailed description with trigger keywords ✅ Test with 3+ real scenarios before documenting ✅ Iterate based on actual usage --- ## Enforcement Levels ### BLOCK (Critical Guardrails) - Physically prevents Edit/Write tool execution - Exit code 2 from hook, stderr → Claude - Claude sees message and must use skill to proceed - **Use For**: Critical mistakes, data integrity, security issues **Example:** Database column name verification ### SUGGEST (Recommended) - Reminder injected before Claude sees prompt - Claude is aware of relevant skills - Not enforced, just advisory - **Use For**: Domain guidance, best practices, how-to guides **Example:** Frontend development guidelines ### WARN (Optional) - Low priority suggestions - Advisory only, minimal enforcement - **Use For**: Nice-to-have suggestions, informational reminders **Rarely used** - most skills are either BLOCK or SUGGEST. --- ## Memory-Aware Skills ### Purpose Skills that maintain context across sessions, learn from user interactions, and persist preferences for long-term workflows. ### When to Use Automatically activates when you mention: - Persisting user preferences or project conventions - Multi-session feature development - Learning from user corrections - Plan-approval workflows - Context that should survive Claude restarts ### Key Capabilities **1. Context Persistence** - Remember user preferences across sessions - Track project-specific conventions - Maintain long-running feature state - Store user corrections and patterns **2. Plan-Approval Workflows** - Generate detailed plans before execution - Require explicit user confirmation - Learn from approved/rejected plans - Provide rollback mechanisms **3. Session State Management** - Track more than "skill used" flag - Store user choices and patterns - Accumulate context over time - Intelligent refresh/invalidation ### Implementation Guide See [MEMORY_PATTERNS.md](MEMORY_PATTERNS.md) for comprehensive patterns: - Context persistence mechanisms - Plan-approve-execute workflow - User preference tracking - Memory refresh triggers - Session state schemas - Privacy and security considerations ### Example: User Preference Memory ```json // .claude/memory/database-verification/preferences.json { "auto_approve_tables": ["users", "posts", "comments"], "always_verify_tables": ["payments", "sensitive_data"], "column_name_preference": "camelCase", "last_updated": "2025-01-15T10:30:00Z" } ``` After user corrects column naming twice, skill remembers and auto-applies. ### Best Practices ✅ **DO**: - Store memory in `.claude/memory/{skill-name}/` - Include timestamps for staleness detection - Provide user control (view/clear memory) - Gracefully handle missing/corrupted memory - Log memory updates for transparency ❌ **DON'T**: - Store sensitive data without encryption - Assume memory is always valid (check staleness) - Persist everything (be selective) - Make memory opaque (user should understand what's stored) --- ## Skip Conditions & User Control ### 1. Session Tracking **Purpose:** Don't nag repeatedly in same session **How it works:** - First edit → Hook blocks, updates session state - Second edit (same session) → Hook allows - Different session → Blocks again **State File:** `.claude/hooks/state/skills-used-{session_id}.json` ### 2. File Markers **Purpose:** Permanent skip for verified files **Marker:** `// @skip-validation` **Usage:** ```typescript // @skip-validation import { PrismaService } from './prisma'; // This file has been manually verified ``` **NOTE:** Use sparingly - defeats the purpose if overused ### 3. Environment Variables **Purpose:** Emergency disable, temporary override **Global disable:** ```bash export SKIP_SKILL_GUARDRAILS=true # Disables ALL PreToolUse blocks ``` **Skill-specific:** ```bash export SKIP_DB_VERIFICATION=true export SKIP_ERROR_REMINDER=true ``` --- ## Testing Checklist When creating a new skill, verify: - [ ] Skill file created in `.claude/skills/{name}/SKILL.md` - [ ] Proper frontmatter with name and description - [ ] Entry added to `skill-rules.json` - [ ] Keywords tested with real prompts - [ ] Intent patterns tested with variations - [ ] File path patterns tested with actual files - [ ] Content patterns tested against file contents - [ ] Block message is clear and actionable (if guardrail) - [ ] Skip conditions configured appropriately - [ ] Priority level matches importance - [ ] No false positives in testing - [ ] No false negatives in testing - [ ] Performance is acceptable (<100ms or <200ms) - [ ] JSON syntax validated: `jq . skill-rules.json` - [ ] **SKILL.md under 500 lines** ⭐ - [ ] Reference files created if needed - [ ] Table of contents added to files > 100 lines --- ## Reference Files For detailed information on specific topics, see: ### [TRIGGER_TYPES.md](TRIGGER_TYPES.md) Complete guide to all trigger types: - Keyword triggers (explicit topic matching) - Intent patterns (implicit action detection) - File path triggers (glob patterns) - Content patterns (regex in files) - Best practices and examples for each - Common pitfalls and testing strategies ### [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) Complete skill-rules.json schema: - Full TypeScript interface definitions - Field-by-field explanations - Complete guardrail skill example - Complete domain skill example - Validation guide and common errors ### [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md) Deep dive into hook internals: - UserPromptSubmit flow (detailed) - PreToolUse flow (detailed) - Exit code behavior table (CRITICAL) - Session state management - Performance considerations ### [TROUBLESHOOTING.md](TROUBLESHOOTING.md) Comprehensive debugging guide: - Skill not triggering (UserPromptSubmit) - PreToolUse not blocking - False positives (too many triggers) - Hook not executing at all - Performance issues ### [PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md) Ready-to-use pattern collection: - Intent pattern library (regex) - File path pattern library (glob) - Content pattern library (regex) - Organized by use case - Copy-paste ready ### [ADVANCED.md](ADVANCED.md) Future enhancements and ideas: - Dynamic rule updates - Skill dependencies - Conditional enforcement - Skill analytics - Skill versioning --- ## Quick Reference Summary ### Create New Skill (5 Steps) 1. Create `.claude/skills/{name}/SKILL.md` with frontmatter 2. Add entry to `.claude/skills/skill-rules.json` 3. Test with `npx tsx` commands 4. Refine patterns based on testing 5. Keep SKILL.md under 500 lines ### Trigger Types - **Keywords**: Explicit topic mentions - **Intent**: Implicit action detection - **File Paths**: Location-based activation - **Content**: Technology-specific detection See [TRIGGER_TYPES.md](TRIGGER_TYPES.md) for complete details. ### Enforcement - **BLOCK**: Exit code 2, critical only - **SUGGEST**: Inject context, most common - **WARN**: Advisory, rarely used ### Skip Conditions - **Session tracking**: Automatic (prevents repeated nags) - **File markers**: `// @skip-validation` (permanent skip) - **Env vars**: `SKIP_SKILL_GUARDRAILS` (emergency disable) ### Anthropic Best Practices ✅ **500-line rule**: Keep SKILL.md under 500 lines ✅ **Progressive disclosure**: Use reference files for details ✅ **Table of contents**: Add to reference files > 100 lines ✅ **One level deep**: Don't nest references deeply ✅ **Rich descriptions**: Include all trigger keywords (max 1024 chars) ✅ **Test first**: Build 3+ evaluations before extensive documentation ✅ **Gerund naming**: Prefer verb + -ing (e.g., "processing-pdfs") ### Troubleshoot Test hooks manually: ```bash # UserPromptSubmit echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts # PreToolUse cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts {"tool_name":"Edit","tool_input":{"file_path":"test.ts"}} EOF ``` See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.