skill-developer

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.

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

---

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)

---

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

---

Step 1: Create Skill File

Location: .claude/skills/{skill-name}/SKILL.md

Template:

```markdown

---

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

What this skill helps with

Specific scenarios and conditions

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](SKILL_RULES_REFERENCE.md) for complete schema.

Basic Template:

```json

{

"my-new-skill": {

"type": "domain",

"enforcement": "suggest",

"priority": "medium",

"promptTriggers": {

"keywords": ["keyword1", "keyword2"],

"intentPatterns": ["(create|add).*?something"]

}

}

}

```

Step 3: Test Triggers

Test UserPromptSubmit:

```bash

echo '{"session_id":"test","prompt":"your test prompt"}' | \

npx tsx .claude/hooks/skill-activation-prompt.ts

```

Test PreToolUse:

```bash

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

---

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.

---

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:

```typescript

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

```bash

export SKIP_SKILL_GUARDRAILS=true # Disables ALL PreToolUse blocks

```

Skill-specific:

```bash

export SKIP_DB_VERIFICATION=true

export SKIP_ERROR_REMINDER=true

```

---

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

---

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

---

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:

```bash

# 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](TROUBLESHOOTING.md) for complete debugging guide.

---

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