# ============================================================================
# CleverAgents Skill Configuration Schema
# ============================================================================
#
# Formal YAML schema definition for skill configuration files.
# Skills are reusable, namespaced collections of tools registered via:
#   agents skill add --config <file>
#
# This schema is based on the formal JSON Schema defined in
# docs/specification.md (Section "Skill Configuration Files → JSON Schema",
# lines 15157-15362).
#
# Schema Version: 1
# ============================================================================

schema_version: "1"

# ----------------------------------------------------------------------------
# Top-Level Fields
# ----------------------------------------------------------------------------

fields:
  # ─── Identity ─────────────────────────────────────────────────
  name:
    type: string
    required: true
    pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
    description: >
      Fully qualified skill name in <namespace>/<name> format.
      Examples: local/file-reader, myorg/devops-toolkit

  description:
    type: string
    required: false
    description: >
      Human-readable description of what this skill provides.

  # ─── Tool References ─────────────────────────────────────────
  tools:
    type: array
    required: false
    description: >
      References to named tools from the Tool Registry.
    items:
      type: object
      required_fields: [name]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
          description: "Fully qualified name of a tool registered in the Tool Registry."
        description:
          type: string
          required: false
          description: "Override the tool's registered description within this skill context."
        writes:
          type: boolean
          required: false
          description: "Override the tool's writes capability flag."
        checkpointable:
          type: boolean
          required: false
          description: "Override the tool's checkpointable capability flag."

  # ─── Inline (Anonymous) Tools ────────────────────────────────
  inline_tools:
    type: array
    required: false
    description: >
      Anonymous tool definitions that exist only within this skill.
      Not registered in the Tool Registry.
    items:
      type: object
      required_fields: [name, source, code]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          description: "Tool name, unique within this skill."
        description:
          type: string
          required: false
          description: "Human-readable description of the tool's purpose."
        source:
          type: string
          required: true
          const: custom
          description: "Source type. Always 'custom' for inline tools."
        code:
          type: string
          required: true
          description: >
            Python code defining the tool's behavior.
            Must contain a run(input_data) function.
        input_schema:
          type: object
          required: false
          description: "JSON Schema describing the tool's input parameters."
        writes:
          type: boolean
          required: false
          default: false
          description: "Whether this tool performs write operations."
        checkpointable:
          type: boolean
          required: false
          default: false
          description: "Whether this tool supports checkpointing."
        side_effects:
          type: array
          required: false
          default: []
          items:
            type: string
          description: >
            Descriptions of side effects (e.g., 'network_call', 'schema_mutation').

  # ─── Included Skills ─────────────────────────────────────────
  includes:
    type: array
    required: false
    description: >
      Other skills whose tools are merged into this skill.
    items:
      type: object
      required_fields: [name]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          pattern: "^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$"
          description: "Fully qualified skill name to include."
        description:
          type: string
          required: false
          description: "Override the included skill's description."

  # ─── MCP Server Specifications ───────────────────────────────
  mcp_servers:
    type: array
    required: false
    description: >
      MCP server specifications for exposing remote tools.
    items:
      type: object
      required_fields: [name, transport]
      additional_properties: false
      fields:
        name:
          type: string
          required: true
          description: "Identifier for the MCP server."
        transport:
          type: string
          required: true
          enum: [stdio, sse, streamable-http]
          description: "Transport protocol."
        command:
          type: string
          required: false
          description: "Command to start the server (required for stdio transport)."
        args:
          type: array
          required: false
          items:
            type: string
          description: "Command-line arguments for the server command."
        env:
          type: object
          required: false
          additional_properties:
            type: string
          description: "Environment variables to set when starting the server."
        url:
          type: string
          required: false
          format: uri
          description: "Server URL (required for sse and streamable-http transports)."
        headers:
          type: object
          required: false
          additional_properties:
            type: string
          description: "HTTP headers for remote server connections."
        tool_filter:
          type: object
          required: false
          additional_properties: false
          fields:
            include:
              type: array
              required: false
              items:
                type: string
              description: "Whitelist of tool names to expose."
            exclude:
              type: array
              required: false
              items:
                type: string
              description: "Blacklist of tool names to hide."

  # ─── Agent Skills Standard Folders ───────────────────────────
  agent_skill_folders:
    type: array
    required: false
    description: >
      References to Agent Skills Standard (SKILL.md-based) tool bundles.
    items:
      type: object
      required_fields: [path]
      additional_properties: false
      fields:
        path:
          type: string
          required: true
          description: "Path to the folder containing SKILL.md."
        name:
          type: string
          required: false
          description: "Override the skill bundle name."

# ----------------------------------------------------------------------------
# Constraints
# ----------------------------------------------------------------------------

required: [name]
additional_properties: false

# ----------------------------------------------------------------------------
# Key Normalization
# ----------------------------------------------------------------------------
# The schema loader accepts camelCase keys and normalizes them to snake_case:
#   inlineTools     -> inline_tools
#   mcpServers      -> mcp_servers
#   agentSkillFolders -> agent_skill_folders
#   inputSchema     -> input_schema
#   sideEffects     -> side_effects
#   toolFilter      -> tool_filter
# Legacy camelCase keys emit a warning but are accepted.