skill-rules.json - Complete Reference

Complete schema and configuration reference for .claude/skills/skill-rules.json.

Table of Contents

• File Location
• Complete TypeScript Schema
• Field Guide
• Example: Guardrail Skill
• Example: Domain Skill
• Validation

---

File Location

Path: .claude/skills/skill-rules.json

This JSON file defines all skills and their trigger conditions for the auto-activation system.

---

Complete TypeScript Schema

interface SkillRules {
    version: string;
    skills: Record<string, SkillRule>;
}

interface SkillRule {
    type: 'guardrail' | 'domain';
    enforcement: 'block' | 'suggest' | 'warn';
    priority: 'critical' | 'high' | 'medium' | 'low';

    promptTriggers?: {
        keywords?: string[];
        intentPatterns?: string[];  // Regex strings
    };

    fileTriggers?: {
        pathPatterns: string[];     // Glob patterns
        pathExclusions?: string[];  // Glob patterns
        contentPatterns?: string[]; // Regex strings
        createOnly?: boolean;       // Only trigger on file creation
    };

    blockMessage?: string;  // For guardrails, {file_path} placeholder

    skipConditions?: {
        sessionSkillUsed?: boolean;      // Skip if used in session
        fileMarkers?: string[];          // e.g., ["@skip-validation"]
        envOverride?: string;            // e.g., "SKIP_DB_VERIFICATION"
    };
}

---

Field Guide

Top Level

SkillRule Fields

*Required for guardrails

promptTriggers Fields

fileTriggers Fields

*Required if fileTriggers is present

skipConditions Fields

---

Example: Guardrail Skill

Complete example of a blocking guardrail skill with all features:

{
  "database-verification": {
    "type": "guardrail",
    "enforcement": "block",
    "priority": "critical",

    "promptTriggers": {
      "keywords": [
        "prisma",
        "database",
        "table",
        "column",
        "schema",
        "query",
        "migration"
      ],
      "intentPatterns": [
        "(add|create|implement).*?(user|login|auth|tracking|feature)",
        "(modify|update|change).*?(table|column|schema|field)",
        "database.*?(change|update|modify|migration)"
      ]
    },

    "fileTriggers": {
      "pathPatterns": [
        "**/schema.prisma",
        "**/migrations/**/*.sql",
        "database/src/**/*.ts",
        "form/src/**/*.ts",
        "email/src/**/*.ts",
        "users/src/**/*.ts",
        "projects/src/**/*.ts",
        "utilities/src/**/*.ts"
      ],
      "pathExclusions": [
        "**/*.test.ts",
        "**/*.spec.ts"
      ],
      "contentPatterns": [
        "import.*[Pp]risma",
        "PrismaService",
        "prisma\\\\.",
        "\\\\.findMany\\\\(",
        "\\\\.findUnique\\\\(",
        "\\\\.findFirst\\\\(",
        "\\\\.create\\\\(",
        "\\\\.createMany\\\\(",
        "\\\\.update\\\\(",
        "\\\\.updateMany\\\\(",
        "\\\\.upsert\\\\(",
        "\\\\.delete\\\\(",
        "\\\\.deleteMany\\\\("
      ]
    },

    "blockMessage": "⚠️ BLOCKED - Database Operation Detected\
\
📋 REQUIRED ACTION:\
1. Use Skill tool: 'database-verification'\
2. Verify ALL table and column names against schema\
3. Check database structure with DESCRIBE commands\
4. Then retry this edit\
\
Reason: Prevent column name errors in Prisma queries\
File: {file_path}\
\
💡 TIP: Add '// @skip-validation' comment to skip future checks",

    "skipConditions": {
      "sessionSkillUsed": true,
      "fileMarkers": [
        "@skip-validation"
      ],
      "envOverride": "SKIP_DB_VERIFICATION"
    }
  }
}

Key Points for Guardrails

1. type: Must be "guardrail"
2. enforcement: Must be "block"
3. priority: Usually "critical" or "high"
4. blockMessage: Required, clear actionable steps
5. skipConditions: Session tracking prevents repeated nagging
6. fileTriggers: Usually has both path and content patterns
7. contentPatterns: Catch actual usage of technology

---

Example: Domain Skill

Complete example of a suggestion-based domain skill:

{
  "project-catalog-developer": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",

    "promptTriggers": {
      "keywords": [
        "layout",
        "layout system",
        "grid",
        "grid layout",
        "toolbar",
        "column",
        "cell editor",
        "cell renderer",
        "submission",
        "submissions",
        "blog dashboard",
        "datagrid",
        "data grid",
        "CustomToolbar",
        "GridLayoutDialog",
        "useGridLayout",
        "auto-save",
        "column order",
        "column width",
        "filter",
        "sort"
      ],
      "intentPatterns": [
        "(how does|how do|explain|what is|describe).*?(layout|grid|toolbar|column|submission|catalog)",
        "(add|create|modify|change).*?(toolbar|column|cell|editor|renderer)",
        "blog dashboard.*?"
      ]
    },

    "fileTriggers": {
      "pathPatterns": [
        "frontend/src/features/submissions/**/*.tsx",
        "frontend/src/features/submissions/**/*.ts"
      ],
      "pathExclusions": [
        "**/*.test.tsx",
        "**/*.test.ts"
      ]
    }
  }
}

Key Points for Domain Skills

1. type: Must be "domain"
2. enforcement: Usually "suggest"
3. priority: "high" or "medium"
4. blockMessage: Not needed (doesn't block)
5. skipConditions: Optional (less critical)
6. promptTriggers: Usually has extensive keywords
7. fileTriggers: May have only path patterns (content less important)

---

Validation

Check JSON Syntax

cat .claude/skills/skill-rules.json | jq .

If valid, jq will pretty-print the JSON. If invalid, it will show the error.

Common JSON Errors

Trailing comma:

{
  "keywords": ["one", "two",]  // ❌ Trailing comma
}

Missing quotes:

{
  type: "guardrail"  // ❌ Missing quotes on key
}

Single quotes (invalid JSON):

{
  'type': 'guardrail'  // ❌ Must use double quotes
}

Validation Checklist

• JSON syntax valid (use jq)
• All skill names match SKILL.md filenames
• Guardrails have blockMessage
• Block messages use {file_path} placeholder
• Intent patterns are valid regex (test on regex101.com)
• File path patterns use correct glob syntax
• Content patterns escape special characters
• Priority matches enforcement level
• No duplicate skill names

---

Related Files:

• SKILL.md - Main skill guide
• TRIGGER_TYPES.md - Complete trigger documentation
• TROUBLESHOOTING.md - Debugging configuration issues