microsoft/hve-core

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/microsoft/hve-core/schemas/agent-frontmatter.schema.json",
  "title": "Agent File Frontmatter Schema",
  "description": "Frontmatter schema for .agent.md files per VS Code custom agent specification",
  "type": "object",
  "required": [
    "description"
  ],
  "properties": {
    "agents": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "string",
          "enum": [
            "*"
          ]
        }
      ],
      "default": "*",
      "description": "List of subagent names allowed to be invoked by this agent. Use '*' to allow all subagents."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "A brief description of the custom agent, shown as placeholder text in the chat input field"
    },
    "name": {
      "type": "string",
      "description": "The name of the custom agent. If not specified, the file name is used"
    },
    "argument-hint": {
      "type": "string",
      "description": "Optional hint text shown in the chat input field to guide users on how to interact with the custom agent"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "A list of tool or tool set names available for this custom agent. Can include built-in tools, tool sets, MCP tools, or tools contributed by extensions"
    },
    "model": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "The AI model(s) to use when running the agent. If not specified, the currently selected model in model picker is used."
    },
    "target": {
      "type": "string",
      "enum": [
        "vscode",
        "github-copilot"
      ],
      "description": "The target environment or context for the custom agent"
    },
    "mcp-servers": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Optional list of Model Context Protocol (MCP) server config json to use with custom agents in GitHub Copilot"
    },
    "user-invokable": {
      "type": "boolean",
      "default": true,
      "description": "Controls whether the agent appears in the UI for manual invocation."
    },
    "disable-model-invocation": {
      "type": "boolean",
      "default": false,
      "description": "When true, prevents this agent from invoking subagents (including other custom agents). It does not affect which model this agent uses or how the model picker works."
    },
    "handoffs": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "label",
          "agent"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "The display text shown on the handoff button"
          },
          "agent": {
            "type": "string",
            "description": "The target agent identifier to switch to"
          },
          "prompt": {
            "type": "string",
            "description": "The prompt text to send to the target agent"
          },
          "model": {
            "type": "string",
            "description": "Optional model override for the handoff."
          },
          "send": {
            "type": "boolean",
            "description": "Optional boolean flag to auto-submit the prompt (default is false)"
          }
        }
      },
      "description": "Optional list of suggested next actions or prompts to transition between custom agents"
    }
  },
  "additionalProperties": false
}