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:

1. Create SKILL.md with YAML frontmatter
2. Add to skill-rules.json with triggers
3. Test detection (UserPromptSubmit hook)
4. Refine patterns based on results
5. 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:

1. Move detailed examples to resources/ subdirectory
2. Extract deep-dive content to topic-specific resource files
3. Use concise summaries in main SKILL.md, point to resources for details
4. 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:

1. Session tracking: Skills are injected once per conversation; subsequent detections reuse already-loaded skills
2. State file: .claude/hooks/state/{conversation_id}-skills-suggested.json tracks loaded skills
3. 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:

1. 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:

1. Pre-commit hook catches broken skill references (automatic)
2. Pre-commit hook suggests new patterns to add (informational)
3. /wrap command reminds you to check skills (manual)
4. Review .claude/skills/ for affected skills
5. 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.sh - UserPromptSubmit (calls skill-activation-prompt.ts)
• .claude/hooks/test-runner-suggestion.sh - Stop event (test suggestions)
• .claude/hooks/lint-check.sh - Stop event (lint 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