Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skill activation, or implementing progressive disclosure. Covers skill structure, YAML frontmatter, trigger types (keywords, intent patterns, file paths, content patterns), enforcement levels (block, suggest, warn), hook mechanisms (UserPromptSubmit, PreToolUse), session tracking, and the 500-line rule.
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-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:
export SKIP_SKILL_GUARDRAILS=true # Disables ALL PreToolUse blocks
