{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/waterr-ai/json-schema/waterr-ai-skill-schema.json",
  "title": "Skill",
  "description": "An invokable instruction pack. Only the one-line `trigger` sits in the agent's prompt each turn; the full `instructions` load when the agent invokes the skill mid-meeting and are dropped when the flow completes.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/waterr-ai-api-openapi.yml#/components/schemas/Skill",
  "type": "object",
  "required": [
    "id",
    "name",
    "trigger",
    "instructions",
    "active"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "membership_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "maxLength": 64,
      "pattern": "^[a-zA-Z0-9_-]{1,64}$",
      "description": "Identifier the agent passes to `invoke_skill`. Unique per account."
    },
    "trigger": {
      "type": "string",
      "maxLength": 500,
      "description": "One line describing WHEN to invoke this skill. Lives in the base prompt on every turn — keep it short and specific."
    },
    "instructions": {
      "type": "string",
      "maxLength": 8000,
      "description": "The instruction pack, delivered to the agent only after it invokes the skill."
    },
    "gated_tool_names": {
      "type": "array",
      "maxItems": 20,
      "default": [],
      "items": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9_-]{1,64}$"
      },
      "description": "Custom-function names that refuse to execute until this skill is invoked. `[]` means the skill is purely behavioural."
    },
    "active": {
      "type": "boolean",
      "default": true,
      "description": "Account-level kill-switch for the definition."
    },
    "scenarios": {
      "type": "array",
      "description": "Scenarios this skill is attached to. Returned only on the single-skill read.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "position": {
            "type": "integer"
          }
        }
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}