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.

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: 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: Step 3: Test Triggers Test UserPromptSubmit: Test PreToolUse: 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. 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: NOTE: Use sparingly defeats the purpose if overused 3. Environment Variables Purpose: Emergency disable, temporary override Global disable: Skill specific: 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: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide. Related Files Configuration: .claude/skills/skill rules.json Master configuration .claude/hooks/state/ Session tracking .claude/settings.json Hook registration Hooks: .claude/hooks/skill activation prompt.ts UserPromptSubmit .claude/hooks/error handling reminder.ts Stop event (gentle reminders) All Skills: .claude/skills/ /SKILL.md Skill content files Skill Status : COMPLETE Restructured following Anthropic best practices ✅ Line Count : < 500 (following 500 line rule) ✅ Progressive Disclosure : Reference files for detailed information ✅ Next : Create more skills, refine patterns based on usage Limitations Use this skill only when the task clearly matches the scope described above. Do not treat the output as a substitute for environment specific validation, testing, or expert review. Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

skill-developer