Skip to content
skill-developer logo

Skill Developer Guide

skill-developer

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

rootcastleco/rei-skills0installs6stars

SKILL.md

Full skill instructions

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)

  1. Create .claude/​skills/​{name}/​SKILL.md with frontmatter
  2. Add entry to .claude/​skills/​skill-rules.json
  3. Test with npx tsx commands
  4. Refine patterns based on testing
  5. 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


🏰 Rei Skills — Curated by Rootcastle Engineering & Innovation | Batuhan Ayrıbaş
Engineering Beyond Boundaries | [email protected]

More skills from rootcastleco

conductor-setup logo
rootcastleco/rei-skills

conductor-setup

Initialize project with Conductor artifacts (product definition,

6 0
View
slo-implementation logo
rootcastleco/rei-skills

slo-implementation

Define and implement Service Level Indicators (SLIs) and Service Level Objectives (SLOs) with error budgets and alerting. Use when establishing reliability targets, implementing SRE practices, or m...

6 0
View
scanning-tools logo
rootcastleco/rei-skills

scanning-tools

This skill should be used when the user asks to \"perform vulnerability scanning\", \"scan networks for open ports\", \"assess web application security\", \"scan wireless networks\", \"detec...

6 0
View
frontend-design logo
rootcastleco/rei-skills

frontend-design

Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard...

6 0
View
auth-implementation-patterns logo
rootcastleco/rei-skills

auth-implementation-patterns

Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing A...

6 0
View
azure-ai-projects-ts logo
rootcastleco/rei-skills

azure-ai-projects-ts

Build AI applications using Azure AI Projects SDK for JavaScript (@azure/ai-projects). Use when working with Foundry project clients, agents, connections, deployments, datasets, indexes, evaluation...

6 0
View
pc-games logo
rootcastleco/rei-skills

pc-games

PC and console game development principles. Engine selection, platform features, optimization strategies.

6 0
View
prompt-caching logo
rootcastleco/rei-skills

prompt-caching

Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache prompt, response cache, cag, cache augm...

6 0
View
kaizen logo
rootcastleco/rei-skills

kaizen

Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements.

6 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View