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.
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.
risk
unknown
source
community
date_added
2026-02-27
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
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.
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:
---
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
✅ 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:
// @skip-validationimport { 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:
export SKIP_SKILL_GUARDRAILS=true# Disables ALL PreToolUse blocks
