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

Architecture

1. UserPromptSubmit Hook (Proactive Suggestions)

• Program: claude-skill-activation
• 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

Configuration File

Location: The skill-rules.json path is determined by:

1. Check UserPromptSubmit hook in .claude/settings.json for file path parameter
2. Default fallback: $CLAUDE_PROJECT_DIR/.claude/skills/skill-rules.json

How to find your path:

• Read .claude/settings.json → hooks.UserPromptSubmit[].command
• Look for the file path argument to claude-skill-activation
• Example: /path/to/claude-skill-activation ~/.claude/skill-rules.json → Your path is ~/.claude/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.

⚠️ CRITICAL: The skill-rules.json file MUST have top-level version and skills fields!

Complete File Template (for NEW file):

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

Adding to Existing File: If skill-rules.json already exists with other skills, add your new skill inside the skills object:

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

Step 3: Test Triggers

# Auto-detects configuration and tests skill activation
test-skill-activation "your test prompt"

# With custom session ID
test-skill-activation -s custom-session "your test prompt"

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

---

Adding Existing Skill to skill-rules.json

If you already have a skill file (SKILL.md) and want to add triggers for it:

Step 1: Find your skill-rules.json path

See Configuration File section above for path discovery instructions.

Step 2: Read existing skill-rules.json (if any)

cat ~/.claude/skill-rules.json  # Use your actual path from Step 1

Step 3: Add skill entry

Use the JSON templates from Quick Start Step 2 above:

• For NEW/EMPTY file → Use "Complete File Template"
• For EXISTING file → Use "Adding to Existing File" template

Step 4: Test the triggers

test-skill-activation "your test prompt"

---

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

---

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 in the references folder:

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 skill-rules.json (⚠️ MUST have version + skills wrapper!)
3. Test with hook command
4. Refine patterns based on testing
5. Keep SKILL.md under 500 lines

Add Existing Skill to skill-rules.json (4 Steps)

1. Find your skill-rules.json path from .claude/settings.json hook command
2. Read existing file (if any) to see current structure
3. Add skill entry to skills object (⚠️ MUST have version + skills wrapper!)
4. Test with hook command: echo '{"session_id":"test","prompt":"..."}' | $HOOK_CMD

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

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-skill-activation "your test prompt"

See TROUBLESHOOTING.md for complete debugging guide.

---

Related Files

Configuration:

• skill-rules.json - Master configuration (path determined by hook command in settings.json)
• .claude/hooks/state/ - Session tracking
• .claude/settings.json - Hook registration (check here for skill-rules.json path)

Hooks:

• Hook command in settings.json (e.g., claude-skill-activation <path>) - UserPromptSubmit

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