skill-developer

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: skill-developer
description: Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skill activation, or implementing progressive disclosure. Covers skill structure, YAML frontmatter, trigger types (keywords, intent patterns, file paths, content patterns), enforcement levels (block, suggest, warn), hook mechanisms (UserPromptSubmit, PreToolUse), session tracking, and the 500-line rule.
---

# 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

### Hook Architecture (five wired hooks)

**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 (regex or optional AI classification)
- **Method**: Injects formatted reminder as context (stdout → Claude's input)
- **Enforcement**: Only `enforcement: "block"` skills are marked MANDATORY; `suggest`/`warn` skills always appear as recommendations

**2. PreToolUse Hook - Skill Verification Guard** (Enforcement)
- **File**: `.claude/hooks/skill-verification-guard.ts`
- **Trigger**: BEFORE Edit/MultiEdit/Write executes
- **Purpose**: Enforce mandatory skill activation (two-try model) and guardrail file/content patterns; optional AI edit analysis
- **Method**: Exit code 2 + stderr blocks the tool; only `enforcement: "block"` skills can block

**3. PostToolUse Hook - Edit Tracker**
- **File**: `.claude/hooks/post-tool-use-tracker.sh`
- **Trigger**: AFTER Edit/MultiEdit/Write completes
- **Purpose**: Track edited files and repos (feeds build checks and the error-handling reminder)

**4. PostToolUse Hook - Skill Activation Tracker**
- **File**: `.claude/hooks/skill-activation-tracker.ts`
- **Trigger**: AFTER the Skill tool runs
- **Purpose**: Clear the activated skill from pending lists so the guard stops blocking

**5. Stop Hook - Session Doc Updater**
- **File**: `.claude/hooks/session-doc-updater.ts`
- **Trigger**: AFTER Claude finishes responding
- **Purpose**: Index dev docs for vector search (Session Intelligence); prunes stale session state

**Optional (shipped but not wired):** `error-handling-reminder.ts` (Stop) — a gentle post-response self-check that analyzes edited files for risky patterns instead of blocking edits.

**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:**
- `frontend-dev-guidelines` - Enforce React/TypeScript patterns (the shipped `block` guardrail)
- A `database-verification` s