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/codanna/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. PreToolUse Hook - Read Validation (Resource Management)

• File: .claude/hooks/codanna/pre_read_use.js
• Trigger: BEFORE Read tool executes
• Purpose: Validate Read operations to prevent excessive line reads
• Method: Checks requested line limit against thresholds, blocks/warns on large reads
• Use Cases: Prevent token waste, encourage efficient file reading patterns
• Thresholds:
• Allow: ≤400 lines (silent)
• Warn: 401-600 lines (logged, shown to Claude)
• Block: >600 lines (operation blocked)

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 [SKILLRULESREFERENCE.md](SKILLRULESREFERENCE.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/codanna/skill-activation-prompt.ts

Test PreToolUse (Read Validation):

cat  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/codanna/state/skills-used-{session_id}.jsonl`

### 2. File Markers

**Purpose:** Permanent skip for verified files

**Marker:** `// @skip-validation`

**Usage:**
```typescript
// @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 ( 100 lines

---

Reference Files

For detailed information on specific topics, see:

[TRIGGERTYPES.md](TRIGGERTYPES.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

[SKILLRULESREFERENCE.md](SKILLRULESREFERENCE.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

[HOOKMECHANISMS.md](HOOKMECHANISMS.md)

Deep dive into hook internals:

• UserPromptSubmit flow (detailed)
• PreToolUse flow (detailed)
• Exit code behavior table (CRITICAL)
• Session state management
• Performance considerations

[TROUBLESHOOTING.md](TROUBLESHOOTING.md)

Comprehensive debugging guide:

• Skill not triggering (UserPromptSubmit)
• PreToolUse not blocking
• False positives (too many triggers)
• Hook not executing at all
• Performance issues

[PATTERNSLIBRARY.md](PATTERNSLIBRARY.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](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 [TRIGGERTYPES.md](TRIGGERTYPES.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/codanna/skill-activation-prompt.ts

# PreToolUse (Read Validation)
cat <<'EOF' | npx tsx .claude/hooks/codanna/pre_read_use.js
{"tool_name":"Read","tool_input":{"file_path":"test.ts","limit":500}}
EOF

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.

---

Related Files

Configuration:

• .claude/skills/skill-rules.json - Master configuration
• .claude/hooks/codanna/state/ - Session tracking
• .claude/settings.local.json - Hook registration

Hooks:

• .claude/hooks/codanna/skill-activation-prompt.ts - UserPromptSubmit
• .claude/hooks/codanna/pre_read_use.js - PreToolUse (Read validation)
• .claude/hooks/codanna/stop.js - Stop event (session end)
• .claude/hooks/codanna/subagent-stop.js - Subagent stop event
• .claude/hooks/codanna/post_tool_use.js - PostToolUse

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: madeinoz67
• Source: madeinoz67/madeinoz-knowledge-system
• License: MIT
• Homepage: https://madeinoz67.github.io/madeinoz-knowledge-system/

Install and usage instructions live in the source repository linked above.