skill-developer

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:

---

System Overview

Two-Hook Architecture

1. UserPromptSubmit Hook (Proactive Suggestions)

2. Stop Hook - Error Handling Reminder (Gentle Reminders)

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:

---

Skill Types

1. Guardrail Skills

Purpose: Enforce critical best practices that prevent errors

Characteristics:

Examples:

When to Use:

2. Domain Skills

Purpose: Provide comprehensive guidance for specific areas

Characteristics:

Examples:

When to Use:

---

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:

Step 2: Add to skill-rules.json

See [SKILL_RULES_REFERENCE.md](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:

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)

Example: Database column name verification

SUGGEST (Recommended)

Example: Frontend development guidelines

WARN (Optional)

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:

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:

---

Reference Files

For detailed information on specific topics, see:

[TRIGGER_TYPES.md](TRIGGER_TYPES.md)

Complete guide to all trigger types:

[SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md)

Complete skill-rules.json schema:

[HOOK_MECHANISMS.md](HOOK_MECHANISMS.md)

Deep dive into hook internals:

[TROUBLESHOOTING.md](TROUBLESHOOTING.md)

Comprehensive debugging guide:

[PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md)

Ready-to-use pattern collection:

[ADVANCED.md](ADVANCED.md)

Future enhancements and ideas:

---

Quick Reference Summary

Create New Skill (5 Steps)

Trigger Types

See [TRIGGER_TYPES.md](TRIGGER_TYPES.md) for complete details.

Enforcement

Skip Conditions

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

---

Related Files

Configuration:

Hooks:

All Skills:

---

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