Skill Developer

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:

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

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

Skill-specific:

export SKIP_DB_VERIFICATION=true
export SKIP_ERROR_REMINDER=true

---

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

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

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

Deep dive into hook internals:

• -UserPromptSubmit flow (detailed)
• -PreToolUse flow (detailed)
• -Exit code behavior table (CRITICAL)
• -Session state management
• -Performance considerations

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

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

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

# UserPromptSubmit
echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts

# PreToolUse
cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
EOF

See 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