Claude Code Skill Developer Guide

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

Hook Architecture (five wired hooks)

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 (regex or optional AI classification)
• Method: Injects formatted reminder as context (stdout → Claude's input)
• Enforcement: Only enforcement: "block" skills are marked MANDATORY; suggest/warn skills always appear as recommendations

2. PreToolUse Hook - Skill Verification Guard (Enforcement)

• File: .claude/hooks/skill-verification-guard.ts
• Trigger: BEFORE Edit/MultiEdit/Write executes
• Purpose: Enforce mandatory skill activation (two-try model) and guardrail file/content patterns; optional AI edit analysis
• Method: Exit code 2 + stderr blocks the tool; only enforcement: "block" skills can block

3. PostToolUse Hook - Edit Tracker

• File: .claude/hooks/post-tool-use-tracker.sh
• Trigger: AFTER Edit/MultiEdit/Write completes
• Purpose: Track edited files and repos (feeds build checks and the error-handling reminder)

4. PostToolUse Hook - Skill Activation Tracker

• File: .claude/hooks/skill-activation-tracker.ts
• Trigger: AFTER the Skill tool runs
• Purpose: Clear the activated skill from pending lists so the guard stops blocking

5. Stop Hook - Session Doc Updater

• File: .claude/hooks/session-doc-updater.ts
• Trigger: AFTER Claude finishes responding
• Purpose: Index dev docs for vector search (Session Intelligence); prunes stale session state

Optional (shipped but not wired): error-handling-reminder.ts (Stop) — a gentle post-response self-check that analyzes edited files for risky patterns instead of blocking edits.

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:

• frontend-dev-guidelines - Enforce React/TypeScript patterns (the shipped block guardrail)
• A database-verification skill verifying table/column names before Prisma queries (hypothetical)

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:

---
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 for complete schema.

Basic Template:

{
  "my-new-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "medium",
    "promptTriggers": {
      "keywords": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?something"]
    }
  }
}

Step 3: Test Triggers

Test UserPromptSubmit:

echo '{"session_id":"test","prompt":"your test prompt"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

Test PreToolUse:

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
• Only enforcement: "block" skills can hard-block — in both the UserPromptSubmit mandatory list and the PreToolUse guardrail checks. suggest/warn matches are always advisory.

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