{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agentskills.io/schema/skill-frontmatter.json",
  "title": "agentskills.io SKILL.md frontmatter",
  "description": "Strict JSON Schema for the YAML frontmatter of a SKILL.md file per the agentskills.io open standard (Anthropic, 2025-12-18). Only `name` and `description` are required; a small optional set is permitted; every other top-level key is a non-standard 'unexpected field'. Constraints that cannot be expressed in JSON Schema (name must equal the parent directory; frontmatter must contain no angle brackets) are enforced by tools/validate-agentskills.py.",
  "type": "object",
  "additionalProperties": false,
  "required": ["name", "description"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
      "description": "1-64 chars, lowercase alphanumeric and single hyphens only; no leading/trailing/consecutive hyphens; must match the parent directory name; must not be a reserved word."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "1-1024 chars. Must state BOTH what the skill does and when to use it."
    },
    "license": {
      "type": "string",
      "minLength": 1,
      "description": "SPDX license identifier or license text."
    },
    "compatibility": {
      "type": "string",
      "maxLength": 500,
      "description": "Free-text compatibility notes (<=500 chars)."
    },
    "metadata": {
      "type": "object",
      "description": "Arbitrary key/value map for non-standard fields. This is where domain, subdomain, tags, version, author, and framework mappings (mitre_attack, nist_csf, atlas_techniques, d3fend_techniques, nist_ai_rmf, mitre_f3) belong under strict compliance.",
      "additionalProperties": true
    },
    "allowed-tools": {
      "description": "EXPERIMENTAL. Tools the skill is permitted to use; string or array of strings.",
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ]
    }
  }
}