name: new-skill description: Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.yaml, 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.

What Makes Skills Valuable

Skills must contain NEW information Claude doesn't already know. The model is trained on the entire internet - generic advice adds nothing.

✅ DO Include

Project-specific patterns - Your actual code conventions, file paths, workflows
Synthesized experience - Lessons from YOUR experiments, failures, discoveries
Concrete examples - Real code, actual commands, specific values
Measurable rules - "Max 5 lines per method" not "keep methods short"
Anti-patterns with specifics - "Avoid purple gradients" not "don't be generic"
Reference files - Deep dives the model can fetch when needed
Domain knowledge not on internet - Internal APIs, proprietary workflows, team conventions

❌ DO NOT Include

Personas - "You are a professional engineer" (model knows this)
Generic advice - "Think step by step", "run tests after changes" (model knows this)
Philosophy without action - "Trust your instincts", "be strategic" (not actionable)
Vague best practices - "Write clean code", "follow best practices" (too broad)
Common frameworks verbatim - Standard TDD/Agile/SOLID (already trained on these)
Motivational content - "You can do it!", "Stay focused" (adds nothing)

The Litmus Test

Ask: "Would this help a human contractor on day one?"

❌ Useless	✅ Valuable
"Run tests after changes"	"Run `bin/rails test test/models/` after touching models"
"Be a strategic thinker"	"Here's our quarterly planning template: [actual template]"
"Write clean code"	"Max 100 lines per class, 5 lines per method (Sandi Metz rules)"
"Think step by step"	"Check these 3 files first: config/routes.rb, then app/controllers/, then app/models/"
"You are an expert Rails developer"	"We use Current.user pattern, Solid Queue for jobs, and this naming convention..."

Hooks vs Skills for Process Enforcement

Critical distinction:

Use	For
Hooks	Process enforcement (deterministic - FORCES behavior)
Skills	Knowledge/context (probabilistic - Claude MAY follow)

If you want Claude to ALWAYS do something (run tests, check types, validate schemas):

❌ Don't make it a skill instruction
✅ Make it a hook that executes automatically

Skills are for knowledge Claude needs, not processes you want enforced.

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.yaml
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.yaml

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

Supported Frontmatter Fields:

name (required) - Skill identifier
description (required) - Trigger keywords and purpose
allowed-tools (optional) - Restrict available tools

NOTE: Skills do NOT support the model: field. Skills inherit the conversation's model.

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.yaml

See 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:

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

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

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

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.yaml 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)

Create .claude/skills/{name}/SKILL.md with frontmatter
Add entry to .claude/skills/skill-rules.yaml
Test with npx tsx commands
Refine patterns based on testing
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 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:

# 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 for complete debugging guide.

Related Files

Configuration:

.claude/skills/skill-rules.yaml - 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

new-skill