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

• Advisory, not mandatory

• Topic or domain-specific

• Comprehensive documentation

• Automatically injected when detected (autoInject: true)

Examples:

• backend-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 (e.g., "See patterns-library.md")

• ✅ Keep files under 500 lines so navigation is unnecessary

• ✅ Use progressive disclosure (link to resource files for deep dives)

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 your skills with multiple real-world scenarios before extensive documentation. Verify triggers activate correctly and content provides useful guidance.

Reference Files

For detailed information on specific topics, see:

trigger-types.md

Complete guide to keyword triggers:

• Keyword triggers (explicit topic matching)

• Best practices and examples

• 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)

• Exit code behavior table (CRITICAL)

• Session state management

• Performance considerations

patterns-library.md

Ready-to-use pattern collection:

• Keyword pattern library

• Organized by use case

• Copy-paste ready

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 constants/utilities in shared modules → Update code-reuse patterns

• New docs in project documentation → Update skill resource file links

• New patterns/features → Update 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 constants/utilities in shared modules: Update skill references and patterns

• New doc: Add link to relevant skill's resources section

• New keyword: Add to promptTriggers.keywords in skill-rules.json

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

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