# 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

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

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

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)

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

{
  "$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
}

{
  "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"]
    }
  }
}

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

// 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);

[ ] 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

# 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

# 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

{
  "$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
}

{
  "$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
}

{
  "$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"
    }
  ]
}

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

{
  "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"]
  }
}

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

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

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

{
  "$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" }
  }
}

# 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 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 JSON example
node .claude/skills/schema-creator/scripts/main.cjs \
  --from-example example.json \
  --output .claude/schemas/generated.schema.json

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 };
}

// .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',
  '.claude/hooks/': '.claude/schemas/hook-definition.schema.json',
};

function validateFile(filePath) {
  // Find matching schema
  for (const [pattern, schemaPath] of Object.entries(schemaMap)) {
    if (filePath.includes(pattern)) {
      const schema = JSON.parse(fs.readFileSync(schemaPath));
      const ajv = new Ajv();
      const validate = ajv.compile(schema);

      // Parse and validate file
      // ...
    }
  }
}

[SKILL-CREATOR] Creating new skill with validation...
  -> Calls schema-creator for input/output schemas
  -> Schemas created in .claude/skills/{skill}/schemas/

[AGENT-CREATOR] Creating agent with strict validation...
  -> Agent uses agent-definition.schema.json for self-validation
  -> Agent validates inputs using custom schemas

[WORKFLOW-CREATOR] Creating workflow with typed steps...
  -> Each step output validates against schema
  -> Workflow uses workflow-definition.schema.json

cat .claude/context/memory/learnings.md

1. NO SCHEMA WITHOUT $schema FIELD
   - Every schema MUST declare its JSON Schema version
   - Use draft-07 or later: "$schema": "https://json-schema.org/draft-07/schema#"

2. NO SCHEMA WITHOUT title AND description
   - Every schema MUST be self-documenting
   - title: Short name of what it validates
   - description: Detailed explanation of purpose

3. NO PROPERTY WITHOUT description
   - Every property MUST have a description
   - Readers should understand field purpose without external docs

4. NO REQUIRED FIELD WITHOUT DEFINITION
   - If field is in "required" array, it MUST be in "properties"
   - Undefined required fields cause silent validation failures

5. NO ADDITIONALPROPERTIES: true WITHOUT REASON
   - Default to additionalProperties: false for strict validation
   - Only allow additional properties when explicitly needed

6. NO SCHEMA WITHOUT VALIDATION TEST
   - Test schema with valid AND invalid examples
   - Schema that passes everything validates nothing

7. NO CREATION WITHOUT SYSTEM IMPACT ANALYSIS
   - Check if related validators need updating
   - Check if documentation needs updating
   - Check if related schemas need cross-references

8. NO SCHEMA WITHOUT CLAUDE.MD REGISTRATION
   - If schema enables new capabilities, update CLAUDE.md
   - Section 4 (Self-Evolution) for agent/skill/workflow schemas
   - Verify with: grep "schema-name" .claude/CLAUDE.md

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

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

# Check all required properties are defined
node -e "const s = require('.claude/schemas/{name}.schema.json'); const r = s.required || []; const p = Object.keys(s.properties || {}); console.log('Missing:', r.filter(x => !p.includes(x)));"

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

[ ] Schema file created with .schema.json extension
[ ] $schema field present (draft-07 or later)
[ ] title and description present
[ ] All properties have descriptions
[ ] required array matches defined properties
[ ] examples included for complex schemas
[ ] Schema validated with test data
[ ] System impact analysis completed
[ ] CLAUDE.md updated if schema enables new capabilities
[ ] Related schemas updated if needed ($ref links)