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 (AI-powered intent analysis, keyword matching), enforcement levels (validation only), hook mechanisms (UserPromptSubmit with auto-injection), 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

Related Skills

When building skills, reference:

testing-strategy - Skills should be tested with real scenarios before extensive documentation
code-reuse-enforcement - Skills should reference existing patterns/utilities from the codebase

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: Meta-skill that maintains 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, adapter 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 (Meta-Skill)

System Overview

The skills system uses a two-tier architecture (meta-skills vs domain skills) with automatic injection to seamlessly provide domain-specific context.

Key concepts:

Meta-skills (e.g., skill-developer): Detected via keywords, provided as context awareness (autoInject: false)
Domain skills (e.g., adapter-development, testing-strategy): Automatically injected when detected (autoInject: true)
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:

Two-tier enforcement logic
Automatic skill detection mechanism
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"
Enforcement: "block" (legacy field, no longer blocks with auto-injection)
Priority: "critical" or "high"
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 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:

api-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

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: NO file should EVER breach 600 lines

Why This Matters:

Agents process files linearly - long files waste tokens and context
500 lines is the sweet spot for focused, scannable content
Progressive disclosure (main file → resource files) is more effective than one giant file

Enforcement Strategy:

If approaching 500 lines → STOP and extract content to resource files
If already > 500 lines → Refactor immediately unless you can justify it's in the top 5 most important files
If approaching 600 lines → MANDATORY refactor, no exceptions

How to Stay Under 500:

Move detailed examples to resources/ subdirectory
Extract deep-dive content to topic-specific resource files
Use concise summaries in main SKILL.md, point to resources for details
Remove redundancy and wordiness

FORBIDDEN: TOCs and Line Number References

NEVER include in skill markdown files:

❌ Table of Contents (TOC) - Bloat for agents, not useful for scanning
❌ Line number references (e.g., "see line 42") - Change too frequently, create maintenance burden
❌ Heading navigation links - Agents can scan headings natively

Why TOCs Are Harmful:

Add 10-50 lines of noise
Agents don't benefit from them (they scan headings natively)
Become stale when structure changes
Waste precious lines toward 500-line limit

Instead:

✅ Use clear, descriptive section headings
✅ Use anchor text for cross-references to resource files
✅ Keep files under 500 lines so navigation is unnecessary
✅ Use progressive disclosure (link to resource files for deep dives)

Enforcement Levels

Note: With auto-injection, enforcement levels are legacy fields that no longer block execution. All skills with autoInject: true are automatically loaded.

BLOCK: (Legacy) Previously prevented tool execution; now just indicates priority for injection
SUGGEST: (Legacy) Previously advisory; now same as BLOCK with auto-injection
WARN: (Legacy) Low priority suggestions; rarely used

Skills are now automatically injected based on detection, regardless of enforcement level. The PreToolUse blocking hook has been removed.

Session State & Deduplication

Automatic session tracking prevents duplicate injection:

Session tracking: Skills are injected once per conversation; subsequent detections reuse already-loaded skills
State file: .claude/hooks/state/{conversation_id}-skills-suggested.json tracks loaded skills
Manual loading: If autoInject: false (meta-skills), use Skill("skill-name") tool manually

Testing & Validation

Test skills manually using the UserPromptSubmit hook:

echo '{"session_id":"debug","prompt":"your test prompt here"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

For detailed trigger testing strategies, see trigger-types.md.

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

two-tier-system.md

Complete two-tier architecture guide:

Meta-skills vs domain skills
Automatic skill detection
Hook flow and enforcement
Workflow examples
Session state management

skill-creation-guide.md

Step-by-step skill creation:

File templates and structure
skill-rules.json configuration
Trigger testing
Pattern refinement
Best practices and common mistakes

Quick Reference

Create New Skill:

Create SKILL.md with frontmatter → 2. Add to skill-rules.json → 3. Test triggers → 4. Refine → 5. Keep < 500 lines

Critical Rules:

✅ 500-line limit (max 5 files can breach, none > 600)
✅ Progressive disclosure (use resource files)
✅ NO TOCs or line numbers (forbidden)
✅ Test before documenting (3+ scenarios)

For Details: See trigger-types.md, hook-mechanisms.md

Self-Healing & Skill Maintenance

Automated Skill Health Checks

The skills system includes automated maintenance to prevent skill drift:

1. Pre-commit Hook - Skill Reference Validator

Script: scripts/pre-commit/validate_skill_references.py
Runs on: Changes to skills, internal docs, or src/ files
Validates:
- All file links in SKILL.md point to existing files (prevents broken refs)
- New internal docs not yet referenced by skills (suggestions)
Exit behavior: Fails on broken links, warns on missing references

2. Manual Checklist - /wrap Command

When wrapping up work, the /wrap command includes a skill update checklist:

New directories/modules → Update skill descriptions to mention them
New constants/utilities in aidb_common → Update code-reuse-enforcement
New docs in docs/developer-guide/ → Update skill resource file links
New patterns/features → Update skill descriptions and promptTriggers keywords

Skill Update Workflow

When code changes:

Pre-commit hook catches broken skill references (automatic)
Pre-commit hook suggests new patterns to add (informational)
/wrap command reminds you to check skills (manual)
Review .claude/skills/ for affected skills
Update skill-rules.json or SKILL.md as needed

Common updates:

New module: Update skill description to mention it for AI intent analysis
New utility: Add reference to code-reuse-enforcement SKILL.md
New doc: Add link to relevant skill's resources section
New keyword: Add to promptTriggers.keywords in skill-rules.json for fallback matching
New concept: Update skill description to help AI understand when to activate the skill

Best Practices for Skill Health

✅ Run /wrap at end of sessions to check for skill updates ✅ Trust pre-commit warnings about unreferenced docs ✅ Keep skill-rules.json in sync with codebase structure ✅ Update skill descriptions when adding new trigger keywords ✅ Test skills after updates to verify triggers still work

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

name

skill-developer

description

Skill Developer Guide

Purpose

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

When building skills, reference:

testing-strategy - Skills should be tested with real scenarios before extensive documentation
code-reuse-enforcement - Skills should reference existing patterns/utilities from the codebase

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: Meta-skill that maintains 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, adapter 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 (Meta-Skill)

System Overview

The skills system uses a two-tier architecture (meta-skills vs domain skills) with automatic injection to seamlessly provide domain-specific context.

Key concepts:

Meta-skills (e.g., skill-developer): Detected via keywords, provided as context awareness (autoInject: false)
Domain skills (e.g., adapter-development, testing-strategy): Automatically injected when detected (autoInject: true)
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:

Two-tier enforcement logic
Automatic skill detection mechanism
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"
Enforcement: "block" (legacy field, no longer blocks with auto-injection)
Priority: "critical" or "high"
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 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:

api-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

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: NO file should EVER breach 600 lines

Why This Matters:

Agents process files linearly - long files waste tokens and context
500 lines is the sweet spot for focused, scannable content
Progressive disclosure (main file → resource files) is more effective than one giant file

Enforcement Strategy:

If approaching 500 lines → STOP and extract content to resource files
If already > 500 lines → Refactor immediately unless you can justify it's in the top 5 most important files
If approaching 600 lines → MANDATORY refactor, no exceptions

How to Stay Under 500:

Move detailed examples to resources/ subdirectory
Extract deep-dive content to topic-specific resource files
Use concise summaries in main SKILL.md, point to resources for details
Remove redundancy and wordiness

FORBIDDEN: TOCs and Line Number References

NEVER include in skill markdown files:

❌ Table of Contents (TOC) - Bloat for agents, not useful for scanning
❌ Line number references (e.g., "see line 42") - Change too frequently, create maintenance burden
❌ Heading navigation links - Agents can scan headings natively

Why TOCs Are Harmful:

Add 10-50 lines of noise
Agents don't benefit from them (they scan headings natively)
Become stale when structure changes
Waste precious lines toward 500-line limit

Instead:

✅ Use clear, descriptive section headings
✅ Use anchor text for cross-references to resource files
✅ Keep files under 500 lines so navigation is unnecessary
✅ Use progressive disclosure (link to resource files for deep dives)

Enforcement Levels

Note: With auto-injection, enforcement levels are legacy fields that no longer block execution. All skills with autoInject: true are automatically loaded.

BLOCK: (Legacy) Previously prevented tool execution; now just indicates priority for injection
SUGGEST: (Legacy) Previously advisory; now same as BLOCK with auto-injection
WARN: (Legacy) Low priority suggestions; rarely used

Skills are now automatically injected based on detection, regardless of enforcement level. The PreToolUse blocking hook has been removed.

Session State & Deduplication

Automatic session tracking prevents duplicate injection:

Session tracking: Skills are injected once per conversation; subsequent detections reuse already-loaded skills
State file: .claude/hooks/state/{conversation_id}-skills-suggested.json tracks loaded skills
Manual loading: If autoInject: false (meta-skills), use Skill("skill-name") tool manually

Testing & Validation

Test skills manually using the UserPromptSubmit hook:

echo '{"session_id":"debug","prompt":"your test prompt here"}' | \
  npx tsx .claude/hooks/skill-activation-prompt.ts

For detailed trigger testing strategies, see trigger-types.md.

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

two-tier-system.md

Complete two-tier architecture guide:

Meta-skills vs domain skills
Automatic skill detection
Hook flow and enforcement
Workflow examples
Session state management

skill-creation-guide.md

Step-by-step skill creation:

File templates and structure
skill-rules.json configuration
Trigger testing
Pattern refinement
Best practices and common mistakes

Quick Reference

Create New Skill:

Create SKILL.md with frontmatter → 2. Add to skill-rules.json → 3. Test triggers → 4. Refine → 5. Keep < 500 lines

Critical Rules:

✅ 500-line limit (max 5 files can breach, none > 600)
✅ Progressive disclosure (use resource files)
✅ NO TOCs or line numbers (forbidden)
✅ Test before documenting (3+ scenarios)

For Details: See trigger-types.md, hook-mechanisms.md

Self-Healing & Skill Maintenance

Automated Skill Health Checks

The skills system includes automated maintenance to prevent skill drift:

1. Pre-commit Hook - Skill Reference Validator

Script: scripts/pre-commit/validate_skill_references.py
Runs on: Changes to skills, internal docs, or src/ files
Validates:
- All file links in SKILL.md point to existing files (prevents broken refs)
- New internal docs not yet referenced by skills (suggestions)
Exit behavior: Fails on broken links, warns on missing references

2. Manual Checklist - /wrap Command

When wrapping up work, the /wrap command includes a skill update checklist:

New directories/modules → Update skill descriptions to mention them
New constants/utilities in aidb_common → Update code-reuse-enforcement
New docs in docs/developer-guide/ → Update skill resource file links
New patterns/features → Update skill descriptions and promptTriggers keywords

Skill Update Workflow

When code changes:

Pre-commit hook catches broken skill references (automatic)
Pre-commit hook suggests new patterns to add (informational)
/wrap command reminds you to check skills (manual)
Review .claude/skills/ for affected skills
Update skill-rules.json or SKILL.md as needed

Common updates:

New module: Update skill description to mention it for AI intent analysis
New utility: Add reference to code-reuse-enforcement SKILL.md
New doc: Add link to relevant skill's resources section
New keyword: Add to promptTriggers.keywords in skill-rules.json for fallback matching
New concept: Update skill description to help AI understand when to activate the skill

Best Practices for Skill Health

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

Next: Create more skills, refine patterns based on usage