Skill Developer

Skill Developer Guide

Purpose

Comprehensive guide for creating and managing Claude Code skills, hooks, agents, and commands. This meta-skill helps you build and configure Claude Code infrastructure components.

When to Use This Skill

• Creating new skills
• Configuring skill triggers in skill-rules.json
• Setting up hooks
• Creating agents
• Adding slash commands
• Understanding skill activation patterns
• Customizing skill behavior

Quick Start

Creating a New Skill

• Create skill directory:

   mkdir -p .claude/skills/{skill-name}

• Create SKILL.md file:

• Add frontmatter with name and description
• Write comprehensive guidelines
• Use progressive disclosure (main file + resources/)

• Update skill-rules.json:
• Add skill entry with triggers
• Configure fileTriggers and promptTriggers
• Set enforcement and priority

Skill Structure

.claude/skills/
  {skill-name}/
    SKILL.md              # Main skill file
    resources/            # Optional: Additional resources
      pattern-1.md
      pattern-2.md

Skill Configuration

skill-rules.json Structure

{
  "version": "1.0",
  "description": "Skill activation triggers",
  "skills": {
    "{skill-name}": {
      "type": "domain" | "guardrail",
      "enforcement": "suggest" | "block" | "warn",
      "priority": "critical" | "high" | "medium" | "low",
      "description": "Skill description",
      "promptTriggers": {
        "keywords": ["keyword1", "keyword2"],
        "intentPatterns": ["regex pattern"]
      },
      "fileTriggers": {
        "pathPatterns": ["app/**/*.tsx"],
        "pathExclusions": ["**/*.test.tsx"],
        "contentPatterns": ["import.*from.*next"]
      }
    }
  }
}

Enforcement Types

• suggest: Skill suggestion appears but doesn't block execution
• block: Requires skill to be used before proceeding (guardrail)
• warn: Shows warning but allows proceeding

Priority Levels

• critical: Highest - Always trigger when matched
• high: Important - Trigger for most matches
• medium: Moderate - Trigger for clear matches
• low: Optional - Trigger only for explicit matches

File Triggers

Path Patterns

Use glob patterns to match file paths:

{
  "pathPatterns": [
    "app/**/*.tsx", // All .tsx files in app/
    "components/**/*.ts", // All .ts files in components/
    "**/*.tsx" // All .tsx files anywhere
  ]
}

Path Exclusions

Exclude files from triggering:

{
  "pathExclusions": [
    "**/*.test.tsx", // Test files
    "**/node_modules/**", // Dependencies
    "**/.next/**" // Build output
  ]
}

Content Patterns

Match file content with regex:

{
  "contentPatterns": [
    "from '@/components/ui/", // Shadcn imports
    "import.*from.*next", // Next.js imports
    "'use client'" // Client component directive
  ]
}

Prompt Triggers

Keywords

Simple keyword matching:

{
  "keywords": ["component", "page", "route", "frontend"]
}

Intent Patterns

Regex patterns for flexible matching:

{
  "intentPatterns": [
    "(create|add|make|build).*?component", // Create component
    "(how to|best practice).*?react", // How to questions
    "app router.*?(page|route)" // App router related
  ]
}

Skill Types

Domain Skills

• Purpose: Provide guidelines for specific domains
• Example: frontend-dev-guidelines, backend-dev-guidelines
• Enforcement: Usually "suggest"

Guardrail Skills

• Purpose: Enforce best practices and prevent mistakes
• Example: Code quality checks, security rules
• Enforcement: Usually "block" or "warn"

Best Practices

Skill Design

• Progressive Disclosure: Main file + resources/ for detailed guides
• Clear Examples: Include working code examples
• Quick Reference: Add quick reference tables
• When to Use: Clearly state when skill applies

Trigger Configuration

• Specific Keywords: Use domain-specific terms
• Flexible Patterns: Use regex for intent matching
• Path Specificity: Match actual project structure
• Avoid Over-triggering: Use exclusions appropriately

File Organization

• Modular Structure: Split large skills into resources/
• Clear Naming: Use descriptive skill names
• Documentation: Document all configuration options

Common Patterns

Tech Stack Specific Skills

{
  "frontend-dev-guidelines": {
    "fileTriggers": {
      "pathPatterns": ["app/**/*.tsx", "components/**/*.tsx"],
      "contentPatterns": ["from '@/components/ui/", "import.*from.*next"]
    },
    "promptTriggers": {
      "keywords": ["component", "shadcn", "next.js"],
      "intentPatterns": ["(create|build).*?component"]
    }
  }
}

Framework Agnostic Skills

{
  "error-tracking": {
    "fileTriggers": {
      "pathPatterns": ["**/*Controller.ts", "**/*Service.ts"],
      "contentPatterns": ["Sentry\\.", "captureException"]
    },
    "promptTriggers": {
      "keywords": ["error", "sentry", "exception"],
      "intentPatterns": ["(add|implement).*?error.*?handling"]
    }
  }
}

Integration Checklist

When adding a new skill:

• [ ] Create skill directory and SKILL.md
• [ ] Write comprehensive guidelines
• [ ] Add to skill-rules.json
• [ ] Configure fileTriggers (pathPatterns, exclusions, contentPatterns)
• [ ] Configure promptTriggers (keywords, intentPatterns)
• [ ] Set appropriate enforcement and priority
• [ ] Test skill activation
• [ ] Document customization needs

Troubleshooting

Skill Not Triggering

• Check pathPatterns match actual file paths
• Verify keywords are spelled correctly
• Test intentPatterns regex patterns
• Check for pathExclusions blocking triggers

Over-triggering

• Add more specific pathPatterns
• Use pathExclusions to filter out files
• Make intentPatterns more specific
• Lower priority level

Skill File Not Found

• Verify skill directory exists: .claude/skills/{skill-name}/
• Check SKILL.md file exists
• Verify skill name matches skill-rules.json entry

Related Skills

• frontend-dev-guidelines: Frontend development patterns
• backend-dev-guidelines: Backend development patterns

Skill Status: Meta-skill for skill development and management