skill-developer
/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 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.
- Author
- torchedhat ↗
- Repository
- ai-marketplace ↗
- Licence
- BSD-3-Clause
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
What it does and when to use it
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.
Original author description
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.
How it works
- Purpose
- When to Use This Skill
- System Overview
- Skill Types
- Quick Start: Creating a New Skill
- Enforcement Levels
- Skip Conditions & User Control
- Testing Checklist
- Reference Files
- Quick Reference Summary
SKILL.md preview
---
name: skill-developer
description: 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.
---
# 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.py`
- **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** (Guardrails)
- **File**: `.claude/hooks/pre-tool-use.py` (future enhancement)
- **Trigger**: BEFORE Edit/Write tool execution
- **Purpose**: Enforce guardrails by blocking problematic operations
- **Method**: Can block tool execution with exit code 2
- **Use Cases**: Critical validations, preventing errors
### 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 database queries
- `code-standards` - Enforce Python/C++ coding standards
**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:**
- `python-dev-guidelines` - Python best practices and patterns
- `cuda-development` - CUDA/GPU programming guidance
- `error-handling` - Error handling and logging patterns
**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:**
```markdown
---
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](SKILL_RULES_REFERENCE.md) for complete schema.
**Basic Template:**
```json
{
"my-new-skill": {
"type": "domain",
"enforcement": "suggest",
"priority": "medium",
"promptTriggers": {
"keywords": ["keyword1", "keyword2"],
"intentPatterns": ["(create|add).*?something"]
}
}
}
```
### Step 3: Test Triggers
**Test UserPromptSubmit:**
```bash
echo '{"session_id":"test","prompt":"your test prompt"}' | \
python3 .claude/hooks/skill-activation-prompt.py
```
**Test PreToolUse:**
```bash
cat <<'EOF' | python3 .claude/hooks/pre-tool-use.py
{"session_id":"test","tool_name":"Edit","tool_input":{"file_path":"test.py"}}
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
**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:**
```python
# @skip-validation
from database import db_service
# This file has been manually verified
```
**NOTE:** Use sparingly - defeats the purpose if overused
### 3. Environment Variables
**Purpose:** Emergency disable, temporary override
**Global disable:**
```bash
export SKIP_SKILL_GUARDRAILS=true # Disables ALL PreToolUse blocks
```
**Skill-specific:**
```bash
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](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](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](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](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](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](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 `python3` 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](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:
```bash
# UserPromptSubmit
echo '{"prompt":"test"}' | python3 .claude/hooks/skill-activation-prompt.py
# PreToolUse
cat <<'EOF' | python3 .claude/hooks/pre-tool-use.py
{"tool_name":"Edit","tool_input":{"file_path":"test.py"}}
EOF
```
See [TROUBLESHOOTING.md](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.py` - UserPromptSubmit
- `.claude/hooks/post-tool-use-tracker.py` - PostToolUse (file tracking)
**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
Files in this package (7)
- ADVANCED.md 4 KB
- HOOK_MECHANISMS.md 8 KB
- PATTERNS_LIBRARY.md 3 KB
- SKILL.md 11 KB
- SKILL_RULES_REFERENCE.md 8 KB
- TRIGGER_TYPES.md 7 KB
- TROUBLESHOOTING.md 10 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · torchedhat/ai-marketplace | 100 | BSD-3-Clause |
| rootcastleco/rei-skills | 100 | MIT |
| davila7/claude-code-templates | 100 | MIT |
| jefflester/claude-skills-supercharged | 100 | MIT |
| grasmash/drupal-claude-skills | 100 | MIT |
| diet103/claude-code-infrastructure-showcase | 100 | MIT |
Database snapshot: 13.11.2026 · package version c94916214809 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100claude-skills
Guide for creating Agent Skills with progressive disclosure and best practices. Use when creating new skills, understanding skill structure, or implementing progressive disclosure. - 100create-hooks
Expert guidance for creating, configuring, and using Claude Code hooks. Use when working with hooks, setting up event listeners, validating commands, automating workflows, adding notifications, or understanding hook types (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit, etc). - 100skill-authoring
Creates and improves Claude Code Skills (SKILL.md files). Covers frontmatter, descriptions, progressive disclosure, bundled resources, and content guidelines. Follows official Anthropic best practices. USE WHEN: user mentions "create skill", "write skill", "SKILL.md", "skill… - 100hook-development
Use when creating, modifying, or debugging Claude Code hooks — PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification. Covers the plugin `hooks/hooks.json` wrapper format vs. the user `settings.json` direct format,… - 95creating-agent-skills
Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices. - 87agent-skills
Authoring Agent Skills — SKILL.md format and frontmatter, progressive disclosure and token budgeting, Anthropic's authoring best practices, bundling references/scripts, and packaging skills for Claude Code, claude.ai, and the Skills API. WHEN: \"write a SKILL.md\", \"create an…