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: `