schema-creator

WARNING: DO NOT WRITE DIRECTLY TO .claude/schemas/

Schema files are protected by unified-creator-guard.cjs (Gate 4 in CLAUDE.md). Direct writes bypass post-creation steps (catalog updates, consumer assignment, integration verification). Always use the schema-creator skill workflow for creating schemas. Direct writes create "invisible artifacts" that no validator or agent can discover.

Creates JSON Schema validation files for the Claude Code Enterprise Framework. Schemas enforce type safety, input validation, and structural consistency across skills, agents, hooks, workflows, and custom data structures.

SYSTEM IMPACT ANALYSIS (CRITICAL - DO NOT SKIP)

After creating ANY schema, you MUST:

1. Register in appropriate location (global vs skill-local)
2. Update related validators to use the new schema
3. Add schema reference to CLAUDE.md if globally significant

Verification:

# Verify schema is valid JSON
node -e "JSON.parse(require('fs').readFileSync('.claude/schemas/<schema-name>.json'))"

# Check schema exists
ls .claude/schemas/<schema-name>.json || ls .claude/skills/<skill>/schemas/<schema-name>.json

WHY: Invalid schemas cause silent validation failures. Unregistered schemas are never used.

---

Purpose

Schemas provide structured validation for:

1. Skill Inputs/Outputs - Validate data passed to and from skills
2. Agent Definitions - Validate agent YAML frontmatter and structure
3. Hook Definitions - Validate hook configuration and registration
4. Workflow Definitions - Validate workflow steps and configuration
5. Custom Data Structures - Validate project-specific data formats

Schema Types

| Type | Location | Purpose | | ------------------- | -------------------------------------------------- | -------------------------------- | | Skill Input | .claude/skills/{name}/schemas/input.schema.json | Validate skill invocation inputs | | Skill Output | .claude/skills/{name}/schemas/output.schema.json | Validate skill execution outputs | | Agent Definition | .claude/schemas/agent-definition.schema.json | Validate agent YAML frontmatter | | Skill Definition | .claude/schemas/skill-definition.schema.json | Validate skill YAML frontmatter | | Hook Definition | .claude/schemas/hook-definition.schema.json | Validate hook configuration | | Workflow Definition | .claude/schemas/workflow-definition.schema.json | Validate workflow structure | | Custom | .claude/schemas/{name}.schema.json | Project-specific validation |

Reference Schema

Use .claude/schemas/agent-definition.schema.json as the canonical reference schema.

Before finalizing any schema, compare against reference:

• [ ] Follows JSON Schema draft-07 or later (draft-2020-12 preferred)
• [ ] Has $schema, $id, title, description, type fields
• [ ] Required fields are documented in "required" array
• [ ] All properties have description fields
• [ ] Includes examples where helpful
• [ ] Uses proper patterns (kebab-case names, semver versions)

CLAUDE.md Registration (MANDATORY)

After creating a schema, update CLAUDE.md if the schema enables new capabilities:

1. New artifact type schema - Add to relevant section (Section 3 for agents, Section 8.5 for skills)
2. Agent/skill/workflow validation schema - Document in Section 4 (Self-Evolution)
3. Framework-wide schema - Add to Existing Schemas Reference table in this skill

Verification:

grep "schema-name" .claude/CLAUDE.md || echo "WARNING: Schema not registered in CLAUDE.md"

BLOCKING: Schema without documentation may not be discovered by other agents.

Workflow

Step 0: Research Synthesis (MANDATORY - ALWAYS FIRST)

BEFORE creating ANY schema, invoke research-synthesis:

Skill({ skill: 'research-synthesis' });

Research Requirements:

• Minimum 3 Exa searches for JSON Schema best practices
• Review existing schemas in .claude/schemas/ for patterns
• Check schema catalog at .claude/context/artifacts/catalogs/schema-catalog.md
• Identify similar schemas that can be used as references
• Document research findings before proceeding

Why: Research-synthesis ensures schemas follow industry best practices and maintain consistency with existing framework schemas.

---

Step 1: Existence Check and Updater Delegation (MANDATORY - SECOND STEP)

BEFORE creating any schema file, check if it already exists:

1. Check if schema already exists:

   test -f .claude/schemas/<schema-name>.json && echo "EXISTS" || echo "NEW"
   

2. If schema EXISTS:

   • DO NOT proceed with creation

   • Invoke artifact-updater workflow instead:

     Skill({
       skill: 'artifact-updater',
       args: {
         name: '<schema-name>',
         changes: '<description of requested changes>',
         justification: 'Update requested via schema-creator',
       },
     });
     

   • Return updater result and STOP

3. If schema is NEW:

   • Continue with Step 1.1 below

---

Step 1.1: Smart Duplicate Detection (MANDATORY)

Before proceeding with creation, run the 3-layer duplicate check:

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'schema',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

Handle results:

• EXACT_MATCH: Stop creation. Route to schema-updater skill instead: Skill({ skill: 'schema-updater' })
• REGISTRY_MATCH: Warn user — artifact is registered but file may be missing. Investigate before creating. Ask user to confirm.
• SIMILAR_FOUND: Display candidates with scores. Ask user: "Similar artifact(s) exist. Continue with new creation or update existing?"
• NO_MATCH: Proceed to next step.

Override: If user explicitly passes --force, skip this check entirely.

---

Step 1.5: Companion Check

Before proceeding with creation, run the ecosystem companion check:

1. Use companion-check.cjs from .claude/lib/creators/companion-check.cjs
2. Call checkCompanions("schema", "{schema-name}") to identify companion artifacts
3. Review the companion checklist — note which required/recommended companions are missing
4. Plan to create or verify missing companions after this artifact is complete
5. Include companion findings in post-creation integration notes

This step is informational (does not block creation) but ensures the full artifact ecosystem is considered.

---

Step 2: Gather Schema Requirements

Before creating a schema, understand:

1. WHAT data structure are you validating?
   - Skill input/output
   - Agent/skill/hook/workflow definition
   - Custom data format

2. WHERE should the schema live?
   - Global: .claude/schemas/ (framework-wide)
   - Local: .claude/skills/{skill}/schemas/ (skill-specific)

3. WHAT are the required vs optional fields?
   - Required: Must be present for valid data
   - Optional: Enhance but not required

4. WHAT are the validation rules?
   - Types (string, number, boolean, object, array)
   - Patterns (regex for strings)
   - Ranges (min/max for numbers)
   - Enums (allowed values)
   - Lengths (min/max for strings/arrays)

Step 3: Determine Schema Type and Location

| Creating For | Schema Location | Example | | ------------------ | --------------------------------------------------- | -------------------------- | | New skill inputs | .claude/skills/{skill}/schemas/input.schema.json | tdd skill parameters | | New skill outputs | .claude/skills/{skill}/schemas/output.schema.json | tdd skill results | | Global definition | .claude/schemas/{name}.schema.json | test-results.schema.json | | Reusable component | .claude/schemas/components/{name}.schema.json | task-status.schema.json |

Step 4: Analyze Data Structure

Examine existing data or specify expected structure:

// Example: Analyzing skill output structure
const exampleOutput = {
  success: true,
  result: {
    filesCreated: ['src/test.ts'],
    testsGenerated: 5,
    coverage: 85.2,
  },
  metadata: {
    duration: 1234,
    skill: 'test-generator',
  },
};

// Extract schema from example:
// - success: boolean (required)
// - result: object (optional)
// - metadata: object (optional)

Step 5: Generate JSON Schema

Use the schema template and customize:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/{schema-name}",
  "title": "{Schema Title}",
  "description": "{What this schema validates}",
  "type": "object",
  "required": ["field1", "field2"],
  "properties": {
    "field1": {
      "type": "string",
      "description": "Description of field1",
      "minLength": 1,
      "maxLength": 100
    },
    "field2": {
      "type": "number",
      "description": "Description of field2",
      "minimum": 0,
      "maximum": 100
    },
    "optionalField": {
      "type": "boolean",
      "description": "Optional boolean field",
      "default": false
    }
  },
  "additionalProperties": false
}

Step 6: Add Descriptions and Examples

Every property MUST have a description:

{
  "properties": {
    "name": {
      "type": "string",
      "description": "The unique identifier for the resource in lowercase-with-hyphens format",
      "pattern": "^[a-z][a-z0-9-]*$",
      "examples": ["my-skill", "test-generator", "code-reviewer"]
    }
  }
}

Add top-level examples:

{
  "examples": [
    {
      "name": "example-skill",
      "description": "An example skill for demonstration",
      "version": "1.0.0"
    }
  ]
}

Step 7: Create Validation Test

Write a simple test to verify the schema works:

// validate-schema-test.cjs
const Ajv = require('ajv');
const schema = require('./.claude/schemas/my-schema.schema.json');

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

// Test valid data
const validData = {
  /* valid example */
};
console.log('Valid:', validate(validData));

// Test invalid data
const invalidData = {
  /* invalid example */
};
console.log('Invalid:', validate(invalidData));
console.log('Errors:', validate.errors);

Step 8: Post-Creation Schema Registration (Phase 1 Integration)

This step is CRITICAL. After creating the schema artifact, you MUST register it in the schema discovery system.

Phase 1 Context: Phase 1 is responsible for discovering and cataloging schemas for validation. Schemas created without registration are invisible to validators and other systems that need them for data validation.

After schema file is written and validated:

1. Create/Update Schema Registry Entry in appropriate location:

   If registry doesn't exist, create .claude/context/artifacts/schema-catalog.md:

   {
     "schemas": [
       {
         "name": "{schema-name}",
         "id": "{schema-name}",
         "$id": "https://claude.ai/schemas/{schema-name}",
         "type": "{input|output|definition|global|component}",
         "description": "{What this schema validates}",
         "version": "1.0.0",
         "filePath": ".claude/schemas/{schema-name}.schema.json",
         "validatesFor": ["{artifact-type-1}", "{artifact-type-2}"],
         "relatedSchemas": [],
         "usedBy": ["{validator-hook}", "{creator-skill}"]
       }
     ]
   }
   

2. Register with Validators:

   Update any validation hooks that should use this schema:

   • Check .claude/hooks/validation/ for relevant validators
   • Add schema to schemaMap in validators that need it

   Example:

   const schemaMap = {
     '.claude/agents/': '.claude/schemas/agent-definition.schema.json',
     '.claude/schemas/{schema-name}.schema.json': require('./.claude/schemas/{schema-name}.schema.json'),
   };
   

3. Document in .claude/context/artifacts/catalogs/schema-catalog.md:

   Add entry to the schema catalog:

   ### {Schema Title} (`{schema-name}.schema.json`)
   
   **$id:** `https://claude.ai/schemas/{schema-name}`
   
   **Purpose:** {Detailed description of what this schema validates}
   
   **Used by:**
   
   - {Validator/hook 1}
   - {Creator skill 1}
   
   **Root properties:**
   
   - {property-1}: {description}
   - {property-2}: {description}
   
   **Example valid data:**
   
   ```json
   {
     "example": "value"
   }
   ```
   

   Required fields: {List required fields}

   Validation: When data matches this schema, {describe what is validated}

4. Update .claude/CLAUDE.md if Schema Enables New Capabilities:

   If this schema supports new artifact types or validation:

   • Add to relevant section (Section 4.1 for creator schemas, Section 9.7 for schemas directory)
   • Add to "Existing Schemas Reference" table in Step 7 of this skill

   Example entry:

   | `{schema-name}` | `.claude/schemas/` | {Purpose} |
   

5. Update Memory:

   Append to .claude/context/memory/learnings.md:

   ## Schema: {schema-name}
   
   - **Type:** {input|output|definition|global|component}
   - **Validates:** {What artifact/data type}
   - **Purpose:** {Detailed purpose}
   - **$id:** https://claude.ai/schemas/{schema-name}
   - **Validators:** {Which hooks/validators use it}
   - **Related Schemas:** {Any $ref references}
   

Why this matters: Without schema registration:

• Validators cannot discover and use schemas
• Data validation doesn't occur system-wide
• Invalid artifacts are created without detection
• "Invisible artifact" pattern emerges

Phase 1 Integration: Schema registry is the discovery mechanism for Phase 1, enabling validators to find and apply schemas consistently across the system.

Step 9: System Impact Analysis (MANDATORY)

Before marking schema creation complete, verify ALL items:

[ ] Schema file created in correct location
[ ] Schema is valid JSON (parseable)
[ ] Schema has $schema, $id, title, description
[ ] All required fields defined in "required" array
[ ] All properties have descriptions
[ ] Examples included for complex schemas
[ ] Schema registry entry created (Step 7)
[ ] Validators registered with schema (if applicable)
[ ] SCHEMA_CATALOG.md updated (Step 7)
[ ] Related documentation updated

Verification Commands:

# Validate JSON syntax
node -e "JSON.parse(require('fs').readFileSync('.claude/schemas/{name}.schema.json'))"

# Check required fields
node -e "const s = require('.claude/schemas/{name}.schema.json'); console.log('title:', s.title); console.log('description:', s.description);"

# Check schema registry
grep "{schema-name}" .claude/context/artifacts/schema-catalog.md

# List all schemas
ls -la .claude/schemas/*.schema.json

BLOCKING: If any item fails, schema creation is INCOMPLETE. All items must pass.

System Impact Analysis (MANDATORY)

After creating a schema, complete ALL of the following:

1. CLAUDE.md Update

• Add to appropriate section if schema enables new capability
• Section 3 for agent-related schemas
• Section 4.1 for creator ecosystem schemas
• Section 8.5 for skill-related schemas

2. Validator Integration

• Check if hooks should validate against new schema
• Update .claude/hooks/ if schema affects validation
• Add to schemaMap in relevant validators

3. Related Schemas

• Update related schemas if needed ($ref links)
• Check for circular dependencies
• Ensure $id values are unique

4. Documentation

• Update .claude/docs/ if schema documents new pattern
• Add schema to Existing Schemas Reference table
• Update skill-catalog.md if schema is for a new skill

Verification Checklist:

# Check CLAUDE.md registration
grep "{schema-name}" .claude/CLAUDE.md

# Check for $ref usage in other schemas
grep -r "{schema-name}" .claude/schemas/

# Verify no duplicate $id
grep -h "\$id" .claude/schemas/*.json | sort | uniq -d

BLOCKING: Schema creation is NOT complete until all impact analysis items are verified.

Schema Templates

Basic Input Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/skill-name-input",
  "title": "Skill Name Input Schema",
  "description": "Input validation schema for skill-name skill",
  "type": "object",
  "required": [],
  "properties": {
    "target": {
      "type": "string",
      "description": "Target file or directory path"
    },
    "options": {
      "type": "object",
      "description": "Optional configuration",
      "properties": {
        "verbose": {
          "type": "boolean",
          "default": false
        }
      }
    }
  },
  "additionalProperties": false
}

Basic Output Schema

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/skill-name-output",
  "title": "Skill Name Output Schema",
  "description": "Output validation schema for skill-name skill",
  "type": "object",
  "required": ["success"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the skill executed successfully"
    },
    "result": {
      "type": "object",
      "description": "The skill execution result",
      "additionalProperties": true
    },
    "error": {
      "type": "string",
      "description": "Error message if execution failed"
    }
  },
  "additionalProperties": false
}

Definition Schema (for agents, skills, hooks)

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://claude.ai/schemas/entity-definition",
  "title": "Entity Definition Schema",
  "description": "Schema for validating entity definition files",
  "type": "object",
  "required": ["name", "description"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Entity name in lowercase-with-hyphens format"
    },
    "description": {
      "type": "string",
      "minLength": 20,
      "maxLength": 500,
      "description": "Clear description of the entity purpose"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
      "default": "1.0.0",
      "description": "Semantic version number"
    }
  },
  "additionalProperties": true,
  "examples": [
    {
      "name": "my-entity",
      "description": "A sample entity for demonstration purposes",
      "version": "1.0.0"
    }
  ]
}

Common JSON Schema Patterns

String Patterns

{
  "kebab-case": {
    "type": "string",
    "pattern": "^[a-z][a-z0-9-]*$"
  },
  "semver": {
    "type": "string",
    "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
  },
  "file-path": {
    "type": "string",
    "pattern": "^[\\w./-]+$"
  },
  "email": {
    "type": "string",
    "format": "email"
  },
  "url": {
    "type": "string",
    "format": "uri"
  }
}

Enum Patterns

{
  "model": {
    "type": "string",
    "enum": ["sonnet", "opus", "haiku", "inherit"]
  },
  "priority": {
    "type": "string",
    "enum": ["lowest", "low", "medium", "high", "highest"]
  },
  "status": {
    "type": "string",
    "enum": ["pending", "in_progress", "completed", "failed", "blocked"]
  }
}

Array Patterns

{
  "tools": {
    "type": "array",
    "items": { "type": "string" },
    "minItems": 1,
    "uniqueItems": true,
    "description": "List of available tools"
  },
  "skills": {
    "type": "array",
    "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
    "description": "List of skill names"
  }
}

Object Patterns

{
  "config": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "enabled": { "type": "boolean", "default": true },
      "timeout": { "type": "integer", "minimum": 0 }
    }
  },
  "metadata": {
    "type": "object",
    "additionalProperties": true,
    "description": "Arbitrary metadata"
  }
}

Conditional Patterns

{
  "if": {
    "properties": {
      "type": { "const": "mcp" }
    }
  },
  "then": {
    "required": ["server", "command"]
  },
  "else": {
    "required": ["handler"]
  }
}

Using $ref for Reusability

{
  "$defs": {
    "namePattern": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Lowercase with hyphens"
    },
    "toolsList": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    }
  },
  "properties": {
    "name": { "$ref": "#/$defs/namePattern" },
    "tools": { "$ref": "#/$defs/toolsList" }
  }
}

CLI Usage

Create Schema from Template

# Create skill input schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type input \
  --skill my-skill

# Create skill output schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type output \
  --skill my-skill

# Create global schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type global \
  --name my-data-format

# Create definition schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --type definition \
  --entity workflow

Validate Schema

# Validate a schema file
node .claude/skills/schema-creator/scripts/main.cjs \
  --validate .claude/schemas/my-schema.schema.json

# Validate data against schema
node .claude/skills/schema-creator/scripts/main.cjs \
  --validate-data data.json \
  --schema .claude/schemas/my-schema.schema.json

Generate Schema from Example

# Generate schema from JSON example
node .claude/skills/schema-creator/scripts/main.cjs \
  --from-example example.json \
  --output .claude/schemas/generated.schema.json

Integration with Validators

Using Ajv for Runtime Validation

const Ajv = require('ajv');
const addFormats = require('ajv-formats');

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

// Load and compile schema
const schema = require('./.claude/schemas/skill-definition.schema.json');
const validate = ajv.compile(schema);

// Validate data
function validateSkillDefinition(data) {
  const valid = validate(data);
  if (!valid) {
    return {
      valid: false,
      errors: validate.errors.map(e => `${e.instancePath} ${e.message}`),
    };
  }
  return { valid: true };
}

Pre-commit Validation Hook

// .claude/hooks/schema-validator.js
const fs = require('fs');
const path = require('path');
const Ajv = require('ajv');

const schemaMap = {
  '.claude/agents/': '.claude/schemas/agent-definition.schema.json',
  '.claude/skills/': '.claude/schemas/skill-definition.schema.json',
  '.c

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->