# skill-rules.json - Complete Reference

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

## Table of Contents

- [File Location](#file-location)
- [Complete TypeScript Schema](#complete-typescript-schema)
- [Field Guide](#field-guide)
- [Example: Guardrail Skill](#example-guardrail-skill)
- [Example: Domain Skill](#example-domain-skill)
- [Validation](#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

```typescript
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

| Field     | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `version` | string | Yes      | Schema version (currently "1.0") |
| `skills`  | object | Yes      | Map of skill name → SkillRule    |

### SkillRule Fields

| Field            | Type   | Required   | Description                                                    |
| ---------------- | ------ | ---------- | -------------------------------------------------------------- |
| `type`           | string | Yes        | "guardrail" (enforced) or "domain" (advisory)                  |
| `enforcement`    | string | Yes        | "block" (PreToolUse), "suggest" (UserPromptSubmit), or "warn"  |
| `priority`       | string | Yes        | "critical", "high", "medium", or "low"                         |
| `promptTriggers` | object | Optional   | Triggers for UserPromptSubmit hook                             |
| `fileTriggers`   | object | Optional   | Triggers for PreToolUse hook                                   |
| `blockMessage`   | string | Optional\* | Required if enforcement="block". Use `{file_path}` placeholder |
| `skipConditions` | object | Optional   | Escape hatches and session tracking                            |

\*Required for guardrails

### promptTriggers Fields

| Field            | Type     | Required | Description                                |
| ---------------- | -------- | -------- | ------------------------------------------ |
| `keywords`       | string[] | Optional | Exact substring matches (case-insensitive) |
| `intentPatterns` | string[] | Optional | Regex patterns for intent detection        |

### fileTriggers Fields

| Field             | Type     | Required | Description                                 |
| ----------------- | -------- | -------- | ------------------------------------------- |
| `pathPatterns`    | string[] | Yes\*    | Glob patterns for file paths                |
| `pathExclusions`  | string[] | Optional | Glob patterns to exclude (e.g., test files) |
| `contentPatterns` | string[] | Optional | Regex patterns to match file content        |
| `createOnly`      | boolean  | Optional | Only trigger when creating new files        |

\*Required if fileTriggers is present

### skipConditions Fields

| Field              | Type     | Required | Description                                |
| ------------------ | -------- | -------- | ------------------------------------------ |
| `sessionSkillUsed` | boolean  | Optional | Skip if skill already used this session    |
| `fileMarkers`      | string[] | Optional | Skip if file contains comment marker       |
| `envOverride`      | string   | Optional | Environment variable name to disable skill |

---

## Example: Guardrail Skill

Complete example of a blocking guardrail skill with all features:

```json
{
    "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\n\n📋 REQUIRED ACTION:\n1. Use Skill tool: 'database-verification'\n2. Verify ALL table and column names against schema\n3. Check database structure with DESCRIBE commands\n4. Then retry this edit\n\nReason: Prevent column name errors in Prisma queries\nFile: {file_path}\n\n💡 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:

```json
{
    "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

```bash
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:**

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

**Missing quotes:**

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

**Single quotes (invalid JSON):**

```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](SKILL.md) - Main skill guide
- [TRIGGER_TYPES.md](TRIGGER_TYPES.md) - Complete trigger documentation
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debugging configuration issues
