Skill Developer

1---
2name: skill-developer
3description: 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.
4---
5 
6# Skill Developer Guide
7 
8## Purpose
9 
10Comprehensive 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.
11 
12## When to Use This Skill
13 
14Automatically activates when you mention:
15- Creating or adding skills
16- Modifying skill triggers or rules
17- Understanding how skill activation works
18- Debugging skill activation issues
19- Working with skill-rules.json
20- Hook system mechanics
21- Claude Code best practices
22- Progressive disclosure
23- YAML frontmatter
24- 500-line rule
25 
26---
27 
28## System Overview
29 
30### Two-Hook Architecture
31 
32**1. UserPromptSubmit Hook** (Proactive Suggestions)
33- **File**: `.claude/hooks/skill-activation-prompt.ts`
34- **Trigger**: BEFORE Claude sees user's prompt
35- **Purpose**: Suggest relevant skills based on keywords + intent patterns
36- **Method**: Injects formatted reminder as context (stdout → Claude's input)
37- **Use Cases**: Topic-based skills, implicit work detection
38 
39**2. Stop Hook - Error Handling Reminder** (Gentle Reminders)
40- **File**: `.claude/hooks/error-handling-reminder.ts`
41- **Trigger**: AFTER Claude finishes responding
42- **Purpose**: Gentle reminder to self-assess error handling in code written
43- **Method**: Analyzes edited files for risky patterns, displays reminder if needed
44- **Use Cases**: Error handling awareness without blocking friction
45 
46**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.
47 
48### Configuration File
49 
50**Location**: `.claude/skills/skill-rules.json`
51 
52Defines:
53- All skills and their trigger conditions
54- Enforcement levels (block, suggest, warn)
55- File path patterns (glob)
56- Content detection patterns (regex)
57- Skip conditions (session tracking, file markers, env vars)
58 
59---
60 
61## Skill Types
62 
63### 1. Guardrail Skills
64 
65**Purpose:** Enforce critical best practices that prevent errors
66 
67**Characteristics:**
68- Type: `"guardrail"`
69- Enforcement: `"block"`
70- Priority: `"critical"` or `"high"`
71- Block file edits until skill used
72- Prevent common mistakes (column names, critical errors)
73- Session-aware (don't repeat nag in same session)
74 
75**Examples:**
76- `database-verification` - Verify table/column names before Prisma queries
77- `frontend-dev-guidelines` - Enforce React/TypeScript patterns
78 
79**When to Use:**
80- Mistakes that cause runtime errors
81- Data integrity concerns
82- Critical compatibility issues
83 
84### 2. Domain Skills
85 
86**Purpose:** Provide comprehensive guidance for specific areas
87 
88**Characteristics:**
89- Type: `"domain"`
90- Enforcement: `"suggest"`
91- Priority: `"high"` or `"medium"`
92- Advisory, not mandatory
93- Topic or domain-specific
94- Comprehensive documentation
95 
96**Examples:**
97- `backend-dev-guidelines` - Node.js/Express/TypeScript patterns
98- `frontend-dev-guidelines` - React/TypeScript best practices
99- `error-tracking` - Sentry integration guidance
100 
101**When to Use:**
102- Complex systems requiring deep knowledge
103- Best practices documentation
104- Architectural patterns
105- How-to guides
106 
107---
108 
109## Quick Start: Creating a New Skill
110 
111### Step 1: Create Skill File
112 
113**Location:** `.claude/skills/{skill-name}/SKILL.md`
114 
115**Template:**
116```markdown
117---
118name: my-new-skill
119description: Brief description including keywords that trigger this skill. Mention topics, file types, and use cases. Be explicit about trigger terms.
120---
121 
122# My New Skill
123 
124## Purpose
125What this skill helps with
126 
127## When to Use
128Specific scenarios and conditions
129 
130## Key Information
131The actual guidance, documentation, patterns, examples
132```
133 
134**Best Practices:**
135- ✅ **Name**: Lowercase, hyphens, gerund form (verb + -ing) preferred
136- ✅ **Description**: Include ALL trigger keywords/phrases (max 1024 chars)
137- ✅ **Content**: Under 500 lines - use reference files for details
138- ✅ **Examples**: Real code examples
139- ✅ **Structure**: Clear headings, lists, code blocks
140 
141### Step 2: Add to skill-rules.json
142 
143See [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) for complete schema.
144 
145**Basic Template:**
146```json
147{
148  "my-new-skill": {
149    "type": "domain",
150    "enforcement": "suggest",
151    "priority": "medium",
152    "promptTriggers": {
153      "keywords": ["keyword1", "keyword2"],
154      "intentPatterns": ["(create|add).*?something"]
155    }
156  }
157}
158```
159 
160### Step 3: Test Triggers
161 
162**Test UserPromptSubmit:**
163```bash
164echo '{"session_id":"test","prompt":"your test prompt"}' | \
165  npx tsx .claude/hooks/skill-activation-prompt.ts
166```
167 
168**Test PreToolUse:**
169```bash
170cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
171{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
172EOF
173```
174 
175### Step 4: Refine Patterns
176 
177Based on testing:
178- Add missing keywords
179- Refine intent patterns to reduce false positives
180- Adjust file path patterns
181- Test content patterns against actual files
182 
183### Step 5: Follow Anthropic Best Practices
184 
185✅ Keep SKILL.md under 500 lines
186✅ Use progressive disclosure with reference files
187✅ Add table of contents to reference files > 100 lines
188✅ Write detailed description with trigger keywords
189✅ Test with 3+ real scenarios before documenting
190✅ Iterate based on actual usage
191 
192---
193 
194## Enforcement Levels
195 
196### BLOCK (Critical Guardrails)
197 
198- Physically prevents Edit/Write tool execution
199- Exit code 2 from hook, stderr → Claude
200- Claude sees message and must use skill to proceed
201- **Use For**: Critical mistakes, data integrity, security issues
202 
203**Example:** Database column name verification
204 
205### SUGGEST (Recommended)
206 
207- Reminder injected before Claude sees prompt
208- Claude is aware of relevant skills
209- Not enforced, just advisory
210- **Use For**: Domain guidance, best practices, how-to guides
211 
212**Example:** Frontend development guidelines
213 
214### WARN (Optional)
215 
216- Low priority suggestions
217- Advisory only, minimal enforcement
218- **Use For**: Nice-to-have suggestions, informational reminders
219 
220**Rarely used** - most skills are either BLOCK or SUGGEST.
221 
222---
223 
224## Skip Conditions & User Control
225 
226### 1. Session Tracking
227 
228**Purpose:** Don't nag repeatedly in same session
229 
230**How it works:**
231- First edit → Hook blocks, updates session state
232- Second edit (same session) → Hook allows
233- Different session → Blocks again
234 
235**State File:** `.claude/hooks/state/skills-used-{session_id}.json`
236 
237### 2. File Markers
238 
239**Purpose:** Permanent skip for verified files
240 
241**Marker:** `// @skip-validation`
242 
243**Usage:**
244```typescript
245// @skip-validation
246import { PrismaService } from './prisma';
247// This file has been manually verified
248```
249 
250**NOTE:** Use sparingly - defeats the purpose if overused
251 
252### 3. Environment Variables
253 
254**Purpose:** Emergency disable, temporary override
255 
256**Global disable:**
257```bash
258export SKIP_SKILL_GUARDRAILS=true  # Disables ALL PreToolUse blocks
259```
260 
261**Skill-specific:**
262```bash
263export SKIP_DB_VERIFICATION=true
264export SKIP_ERROR_REMINDER=true
265```
266 
267---
268 
269## Testing Checklist
270 
271When creating a new skill, verify:
272 
273- [ ] Skill file created in `.claude/skills/{name}/SKILL.md`
274- [ ] Proper frontmatter with name and description
275- [ ] Entry added to `skill-rules.json`
276- [ ] Keywords tested with real prompts
277- [ ] Intent patterns tested with variations
278- [ ] File path patterns tested with actual files
279- [ ] Content patterns tested against file contents
280- [ ] Block message is clear and actionable (if guardrail)
281- [ ] Skip conditions configured appropriately
282- [ ] Priority level matches importance
283- [ ] No false positives in testing
284- [ ] No false negatives in testing
285- [ ] Performance is acceptable (<100ms or <200ms)
286- [ ] JSON syntax validated: `jq . skill-rules.json`
287- [ ] **SKILL.md under 500 lines** ⭐
288- [ ] Reference files created if needed
289- [ ] Table of contents added to files > 100 lines
290 
291---
292 
293## Reference Files
294 
295For detailed information on specific topics, see:
296 
297### [TRIGGER_TYPES.md](TRIGGER_TYPES.md)
298Complete guide to all trigger types:
299- Keyword triggers (explicit topic matching)
300- Intent patterns (implicit action detection)
301- File path triggers (glob patterns)
302- Content patterns (regex in files)
303- Best practices and examples for each
304- Common pitfalls and testing strategies
305 
306### [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md)
307Complete skill-rules.json schema:
308- Full TypeScript interface definitions
309- Field-by-field explanations
310- Complete guardrail skill example
311- Complete domain skill example
312- Validation guide and common errors
313 
314### [HOOK_MECHANISMS.md](HOOK_MECHANISMS.md)
315Deep dive into hook internals:
316- UserPromptSubmit flow (detailed)
317- PreToolUse flow (detailed)
318- Exit code behavior table (CRITICAL)
319- Session state management
320- Performance considerations
321 
322### [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
323Comprehensive debugging guide:
324- Skill not triggering (UserPromptSubmit)
325- PreToolUse not blocking
326- False positives (too many triggers)
327- Hook not executing at all
328- Performance issues
329 
330### [PATTERNS_LIBRARY.md](PATTERNS_LIBRARY.md)
331Ready-to-use pattern collection:
332- Intent pattern library (regex)
333- File path pattern library (glob)
334- Content pattern library (regex)
335- Organized by use case
336- Copy-paste ready
337 
338### [ADVANCED.md](ADVANCED.md)
339Future enhancements and ideas:
340- Dynamic rule updates
341- Skill dependencies
342- Conditional enforcement
343- Skill analytics
344- Skill versioning
345 
346---
347 
348## Quick Reference Summary
349 
350### Create New Skill (5 Steps)
351 
3521. Create `.claude/skills/{name}/SKILL.md` with frontmatter
3532. Add entry to `.claude/skills/skill-rules.json`
3543. Test with `npx tsx` commands
3554. Refine patterns based on testing
3565. Keep SKILL.md under 500 lines
357 
358### Trigger Types
359 
360- **Keywords**: Explicit topic mentions
361- **Intent**: Implicit action detection
362- **File Paths**: Location-based activation
363- **Content**: Technology-specific detection
364 
365See [TRIGGER_TYPES.md](TRIGGER_TYPES.md) for complete details.
366 
367### Enforcement
368 
369- **BLOCK**: Exit code 2, critical only
370- **SUGGEST**: Inject context, most common
371- **WARN**: Advisory, rarely used
372 
373### Skip Conditions
374 
375- **Session tracking**: Automatic (prevents repeated nags)
376- **File markers**: `// @skip-validation` (permanent skip)
377- **Env vars**: `SKIP_SKILL_GUARDRAILS` (emergency disable)
378 
379### Anthropic Best Practices
380 
381✅ **500-line rule**: Keep SKILL.md under 500 lines
382✅ **Progressive disclosure**: Use reference files for details
383✅ **Table of contents**: Add to reference files > 100 lines
384✅ **One level deep**: Don't nest references deeply
385✅ **Rich descriptions**: Include all trigger keywords (max 1024 chars)
386✅ **Test first**: Build 3+ evaluations before extensive documentation
387✅ **Gerund naming**: Prefer verb + -ing (e.g., "processing-pdfs")
388 
389### Troubleshoot
390 
391Test hooks manually:
392```bash
393# UserPromptSubmit
394echo '{"prompt":"test"}' | npx tsx .claude/hooks/skill-activation-prompt.ts
395 
396# PreToolUse
397cat <<'EOF' | npx tsx .claude/hooks/skill-verification-guard.ts
398{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}
399EOF
400```
401 
402See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for complete debugging guide.
403 
404---
405 
406## Related Files
407 
408**Configuration:**
409- `.claude/skills/skill-rules.json` - Master configuration
410- `.claude/hooks/state/` - Session tracking
411- `.claude/settings.json` - Hook registration
412 
413**Hooks:**
414- `.claude/hooks/skill-activation-prompt.ts` - UserPromptSubmit
415- `.claude/hooks/error-handling-reminder.ts` - Stop event (gentle reminders)
416 
417**All Skills:**
418- `.claude/skills/*/SKILL.md` - Skill content files
419 
420---
421 
422**Skill Status**: COMPLETE - Restructured following Anthropic best practices ✅
423**Line Count**: < 500 (following 500-line rule) ✅
424**Progressive Disclosure**: Reference files for detailed information ✅
425 
426**Next**: Create more skills, refine patterns based on usage
427