Skip to content

copilot-agent-valid

Copilot and VS Code custom agents must use target-compatible frontmatter
Severity error (auto)
Autofix -
Since v0.20.0
Repo Types copilot
Category Copilot / VS Code

Why

GitHub Copilot and VS Code both load custom agents from .github/agents/**/*.md, but they do not consume exactly the same frontmatter. GitHub cloud supports agent-scoped MCP servers and metadata; VS Code adds prioritized model lists, subagents, handoffs, and preview hooks. A syntactically valid field written in the wrong dialect is silently ignored, which leaves a shared agent only partly configured.

This rule validates the common scalar fields, real YAML booleans, tool and model collections, subagent/tool coordination, metadata, handoffs, hook shape, the two documented target values, and GitHub's 30,000-character prompt limit. Files under .github/agents/ target both environments when target is omitted and accept the documented union. Legacy chatmodes default to VS Code. A valid explicit target always wins. Unknown tool names remain valid because both consumers ignore tools they do not provide.

Embedded mcp-servers configurations in cloud or shared agent files are scanned by the shared mcp-valid-json and mcp-prohibited rules. Lifecycle hooks in VS Code-capable agent files are scanned by hooks-dangerous. GitHub template variables (${{ secrets.NAME }} and ${{ vars.NAME }}) are recognized as valid placeholders.

GitHub's local MCP transport is accepted as the cloud spelling of stdio. VS Code command hooks may use command, windows, linux, and osx; every provided command is security-scanned. Hooks on cloud-only agents are ignored.

Severity

Malformed YAML, wrong field types, invalid targets, unusable collections, invalid handoffs or hook structures, missing agent-tool access, and an oversized cloud prompt are errors.

Compatibility findings are warnings because the file remains usable in its selected environment: VS Code-only fields on target: github-copilot, cloud MCP/metadata on target: vscode, a cloud-only tools string in VS Code, and a VS Code model array in cloud. The retired infer field is also a warning; disable-model-invocation takes precedence when both are present.

Unknown top-level fields are accepted by default because the format evolves quickly. Set report-unknown-fields: true to surface them as warnings.

Examples

Bad — the target and types are not recognized, and the subagent cannot be invoked through the restricted tools list:

---
description: Reviews a proposed change
target: github
tools: [read, 42]
agents: [Researcher]
disable-model-invocation: "false"
---

Review the requested changes.

Good for VS Code — the agent tool enables the listed subagents and the handoff uses a qualified model:

---
description: Plans a change and hands approved work to implementation
target: vscode
tools: [read, search, agent]
agents: [Researcher, Implementer]
model: [Claude Sonnet 4.5, GPT-5.2]
handoffs:
  - label: Start Implementation
    agent: Implementer
    send: false
    model: GPT-5.2 (copilot)
---

Create a detailed implementation plan.

How to fix

  • Use target: vscode, target: github-copilot, or omit target for a shared agent.
  • Keep VS Code tools as a YAML list. Add agent, custom-agent, or Task when a non-empty agents list is paired with an explicit tools restriction.
  • Replace quoted booleans with true or false; replace retired infer with user-invocable and disable-model-invocation.
  • Keep handoff label, agent, optional prompt, and optional qualified model values as non-empty strings; keep send as a boolean.
  • Move a field to the environment that consumes it, or remove the explicit target when the file is intentionally shared.

To warn on preview keys this release does not recognize:

rules:
  copilot-agent-valid:
    report-unknown-fields: true

Configuration

rules:
  copilot-agent-valid:
    enabled: auto  # true | false | auto
    severity: error
Parameter Description Default
report-unknown-fields Warn about unknown top-level custom-agent fields; disabled by default because the format evolves quickly false

Run skillsaw explain copilot-agent-valid to see this documentation and the rule's effective configuration in your terminal.