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, keyword triggers, hook mechanisms (UserPromptSubmit), session tracking, and the 500-line rule.
jefflester · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add jefflester/claude-skills-supercharged --skill skill-developerAbout this skill
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, keyword triggers, hook mechanisms (UserPromptSubmit), 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.
Domain Skill for Skill System
This is a domain skill for the skills system itself. It's automatically loaded when you work with skills.
This skill covers:
- The 500-line rule (max 5 files > 500 lines, none > 600 lines)
- TOC and line number prohibition (never add these to skills)
- When skills need updates (new dirs, patterns, docs, triggers)
- Self-healing mechanisms (pre-commit hook, /wrap checklist)
- Progressive disclosure patterns (main file → resource files)
Use this skill explicitly when:
- Creating or modifying any skill
- Debugging skill activation issues
- Understanding the skills system architecture
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
Related Skills
This skill helps create and manage all other skills. When building skills, reference:
- testing-strategy - Skills should be tested with real scenarios before extensive documentation
Relationship to CLAUDE.md
Division of Responsibilities:
- CLAUDE.md: Global project context, high-level architecture, universal style rules
- Skills: Domain-specific detailed guidance, patterns, procedures (triggered by context)
- skill-developer: Domain skill that guides the skills system and explains its relationship to CLAUDE.md
When to Update:
- Global style rules (numpy docstrings, no emojis, use venv) → Update CLAUDE.md
- Domain patterns/practices (test patterns, architecture design) → Update relevant skill
- Skill system mechanics (triggers, hooks, 500-line rule) → Update skill-developer
Integration:
- CLAUDE.md references skills for detailed guidance (1-line pointers)
- Skills don't reference CLAUDE.md (avoid circular dependencies)
- skill-developer explains the complete hierarchy (this section)
Progressive Disclosure Hierarchy:
CLAUDE.md (Global Context)
↓ references
Skills (Domain Guidance)
↓ maintained by
skill-developer (Domain Skill)
System Overview
The skills system uses automatic injection to seamlessly provide domain-specific context when you need it.
Key concepts:
- Domain skills (e.g., python-best-practices, skill-developer): Automatically injected when detected based on prompt keywords and AI intent analysis (autoInject: true)
- Guardrail skills (e.g., api-security): Enforce critical best practices, automatically injected when detected
- Automatic detection & injection: Skills detected via AI-powered intent analysis and immediately loaded into context - no manual intervention needed
For complete details, see two-tier-system.md:
- Skill detection mechanism
- Automatic skill detection and injection
- Hook architecture and flow
- Workflow examples and scenarios
- Session state management
Skill Types
1. Guardrail Skills
Purpose: Enforce critical best practices that prevent errors
Characteristics:
- Type:
"guardrail" - Automatically injected when detected (autoInject: true)
- Prevent common mistakes (column names, critical errors)
- Session-aware (only inject once per conversation)
Examples:
database-verification- Verify table/column names before Prisma queriesfrontend-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" - Advisory, not mandatory
- Topic or domain-specific
- Comprehensive documentation
- Automatically injected when detected (autoInject: true)
Examples:
backend-dev-guidelines- Node.js/Express/TypeScript patternsfrontend-dev-guidelines- React/TypeScript best practiceserror-tracking- Sentry integration guidance
When to Use:
- Complex systems requiring deep knowledge
- Best practices documentation
- Architectural patterns
- How-to guides
Creating New Skills
5-step process:
- Create SKILL.md with YAML frontmatter
- Add to skill-rules.json with triggers
- Test detection (UserPromptSubmit hook)
- Refine patterns based on results
- Keep under 500 lines with progressive disclosure
For complete step-by-step guide, see skill-creation-guide.md:
- File templates and naming conventions
- skill-rules.json configuration
- Trigger testing commands
- Pattern refinement strategies
- Best practices and common mistakes
CRITICAL: The 500-Line Rule
Absolute Limits for ALL Skill Markdown Files:
- ✅ Target: ALL skill files under 500 lines
- ⚠️ Warning Zone: Only 5 files maximum can breach 500 lines across entire skills system (~50 files)
- 🚫 HARD LIMIT: **