skill-developer - Agent Skills

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

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:
[ ] 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:
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)
Create .claude/skills/{name}/SKILL.md with frontmatter

Add entry to .claude/skills/skill-rules.json

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