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:

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

###