Skip to content

Custom agent frontmatter model field rejects array syntax — incompatibility between Copilot CLI and VS Code Copilot Chat #2133

Closed
Bug
Closed
Custom agent frontmatter model field rejects array syntax — incompatibility between Copilot CLI and VS Code Copilot Chat#2133
Bug
Labels
area:agentsSub-agents, fleet, autopilot, plan mode, background agents, and custom agentsarea:modelsModel selection, availability, switching, rate limits, and model-specific behavior

Description

@deyil
deyil
opened on Mar 18, 2026

Describe the bug

When a custom agent .agent.md file uses an array for the model frontmatter field (as supported by VS Code Copilot Chat), the GitHub Copilot CLI refuses to load the agent and throws a parse error.

Error message from Copilot CLI:

The following agents failed to load:
 .github/agents/Coordinator.agent.md: custom agent markdown frontmatter is malformed: model: Expected string, received array

Agent frontmatter that triggers the error:

---
name: Coordinator
description: Pure managerial agent that orchestrates implementation by delegating all technical work to specialized subagents.
argument-hint: Coordinate a plan, phase, feature, or code change
tools: [vscode, execute, read, agent, search, web, todo]
model: [GPT-5.4 (copilot), Claude Sonnet 4.6 (copilot)]
---

The model field being an array is intentional — it allows the agent to declare multiple model fallbacks or alternatives. VS Code Copilot Chat loads and uses this agent correctly. However, the Copilot CLI strictly expects model to be a string, causing a schema validation failure and preventing the agent from loading entirely.

Affected version

No response

Steps to reproduce the behavior

  1. Create a custom agent file at .github/agents/MyAgent.agent.md with the following frontmatter:
---
name: MyAgent
description: An agent with multiple model options
model: [GPT-5.4 (copilot), Claude Sonnet 4.6 (copilot)]
---
  1. Run any copilot CLI command that triggers agent loading (e.g. gh copilot suggest or open a session that scans .github/agents/)
  2. Observe the error output on checking /agent

Expected behavior

The Copilot CLI should accept the model field as either a string or an array of strings, consistent with how VS Code Copilot Chat parses the same .agent.md frontmatter. When an array is provided, the CLI could use the first entry as the primary model, or support model fallback/selection semantics.

At minimum, the schema validation for model should align between Copilot CLI and VS Code Copilot Chat to avoid agents that work in one environment failing to load in the other.

Additional context

No response

Activity

  1. deyil
    added the
    Bug
    issue type on Mar 18, 2026
  2. deyil
    added
    triage
    on Mar 18, 2026

  3. brolnickij commented on Mar 26, 2026

    @brolnickij
    brolnickij
    on Mar 26, 2026

    Hit the same class of issue. In our case it was not array syntax but display names vs slug IDs.

    CLI rejected all of these:

    model: Claude Opus 4.6 (copilot)
model: GPT-5.4 (copilot)
model: Gemini 3 Flash (Preview) (copilot)

    Fix: use slug IDs from ~/.copilot/config.json — claude-opus-4.6, gpt-5.4, claude-haiku-4.5, etc.

    So there are at least 3 incompatibilities between CLI and VS Code for model::

    1. Array syntax (this issue) — CLI rejects, VS Code accepts
    2. Vendor suffix (copilot) — CLI rejects, VS Code uses for handoffs
    3. Display names vs slugs — CLI wants slugs, VS Code wants display names

    Copilot CLI v1.0.11, macOS.

  4. MetalHexx commented on Mar 29, 2026

    @MetalHexx
    MetalHexx
    on Mar 29, 2026

    Yeah this is giving me trouble right now in my RadOrchestration project. I'm trying to make my system work cohesively between the vscode and cli and I'm running into a lot of friction aligning my agent definitions between both tools.

  5. andyfeller
    added
    area:modelsModel selection, availability, switching, rate limits, and model-specific behavior
    on Apr 6, 2026
  6. github-actions
    removed
    triage
    on Apr 6, 2026
  7. andyfeller
    added
    area:agentsSub-agents, fleet, autopilot, plan mode, background agents, and custom agents
    on Apr 6, 2026

  8. cirvine-MSFT commented on Apr 23, 2026

    @cirvine-MSFT
    cirvine-MSFT
    on Apr 23, 2026

    Repro from a real VS Code Team Kit plugin on Copilot CLI 1.0.35-4 / Windows.

    I hit the same incompatibility when installing the vscode-team-kit plugin and opening the custom agents picker in Copilot CLI. The bundled agent definitions load in VS Code, but Copilot CLI warns that the frontmatter is malformed because model is an array.

    Affected files from the installed plugin:

    • C:\Users\cirvine\.copilot\installed-plugins\vscode-team-kit\model-council\agents\councillor-gpt.agent.md
    • C:\Users\cirvine\.copilot\installed-plugins\vscode-team-kit\model-council\agents\councillor-opus.agent.md
    • C:\Users\cirvine\.copilot\installed-plugins\vscode-team-kit\model-council\agents\councillor-gemini.agent.md

    Example frontmatter shape:

    ---
name: Councillor-GPT
description: Read-only code reviewer pinned to GPT models. Use directly for a single-model review, or as part of a multi-model council via the council skills.
user-invocable: false
model:
  - GPT-5.4
  - GPT-5.3-Codex
---

    CLI output:

    custom agent markdown frontmatter is malformed: model: Expected string, received array

    This looks like a real compatibility gap between VS Code agents and Copilot CLI agents. It would be great if agent frontmatter support were uniform across both surfaces, especially for:

    1. model as a string or array of strings
    2. model identifiers / display names being normalized consistently
    3. clear fallback or selection behavior when multiple models are listed

    Right now this blocks using the same agent definitions across VS Code and Copilot CLI without maintaining separate copies.

  9. maddeq commented on Aug 13, 2026

    @maddeq
    maddeq
    on Aug 13, 2026

    Confirming this except we got no visible error or notification at all, /agentjust silently listed none of our custom agents. Had to go digging to find the actual root cause of the disappearing agents.

  10. WilliamBerryiii
    added a commit that references this issue on Aug 14, 2026

    fix(agents): use scalar model in subagent frontmatter for CLI compati…

    ae4b225
  11. yeeshian
    added a commit that references this issue on Aug 14, 2026

    fix(agents): use scalar model in subagent frontmatter for CLI compati…

    d64c064
  12. mlorentedev
    added a commit that references this issue on Aug 22, 2026

    fix(harness): agy takes its model as a launcher flag, so it is an ada…

    358e8ca

  13. patniko commented on Oct 26, 2026

    @patniko
    patniko
    on Oct 26, 2026
    Collaborator

    Thanks for the report. As of Copilot CLI v1.0.83, custom agents can list several models in the model field, tried in order until one is available to you (with model-policy: required keeping model changes on that list), and since v1.0.24 the model field also accepts VS Code-style display names and vendor suffixes such as GPT-5.4 (copilot), so definitions like the one above should now load in both tools. If an agent with a model list still fails to load, or silently goes missing from /agent, on the latest version, please reopen with the frontmatter.

    Triaged as part of a Copilot SDK backlog review, with help from GitHub Copilot.

  14. patniko
    closed this as completedon Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:agentsSub-agents, fleet, autopilot, plan mode, background agents, and custom agentsarea:modelsModel selection, availability, switching, rate limits, and model-specific behavior

    Type

    Bug

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions