Custom agent file reference
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Custom agent file reference View as Markdown Ask in VS Code Ask in VS Code Insiders This article describes custom agent file locations, syntax, frontmatter fields, and harness-specific configuration in VS Code.
For a step-by-step creation and verification workflow, see Create and use custom agents . File structure A custom agent file contains an optional YAML header, enclosed by --- delimiters, followed by a Markdown body with the agent's instructions: --- name : Reviewer description : Review changes without editing files tools : [ 'read' , 'search' ] --- Review the supplied changes for correctness and missing tests. Report actionable findings with file references.
Do not edit files. The fields below describe the VS Code format. Files in .claude/agents use the Claude agent format . Custom agent file locations You can define custom agents for a specific workspace or at the user level, where they are available across your workspaces. Select the intended harness before you create an agent so the Agent Customizations editor stores it in a supported location. Scope Default file location File format Workspace .github/agents folder .agent.md or .md files Workspace (Claude format) .claude/agents folder .md files in the Claude agent format User (Copilot) ~/.copilot/agents folder .agent.md or .md files User (Anthropic Claude) ~/.claude/agents folder .md files in the Claude agent format To create a user-level custom agent, use the Agent Customizations editor or the Chat: New Custom Agent command.
Store the file in a supported folder on the machine where the selected harness runs. In a monorepo, enable chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders to discover custom agents from the parent repository root. Learn more about parent repository discovery . Local harness locations and migration The Local harness The Local harness is deprecated and will be removed in February 2027.
Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . stores user-level custom agents in VS Code profile storage, separate from harness user folders such as ~/.copilot/agents and ~/.claude/agents . To reuse profile-based agents with another harness, move them to that harness's user folder . Prefer native harness folders, such as .github/agents and ~/.copilot/agents , over custom search locations.
The chat.agentFilesLocations Open in VS Code Open in VS Code Insiders setting remains supported and is not deprecated. The editor forwards agents from additional configured locations to Agent Host harnesses, including Copilot, for compatibility with existing editor workflows. The older chat.modeFilesLocations setting is deprecated. Custom locations are not recommended for Copilot workflows because GitHub Copilot CLI and the GitHub Copilot app do not inherit editor location settings.
To use agents across Copilot clients, move them to native harness locations . Custom agents were previously known as custom chat modes. If you have .chatmode.md files, rename them to .agent.md and place them in a supported custom agent location. If an agent has hooks in its frontmatter, review the agent-scoped hook contract . VS Code preserves those hooks when converting agents for Copilot, including plugin-provided agents.
Keep agent-specific automation scoped to the agent and verify that its hooks run before completing a migration. Organization-level agents To share custom agents across multiple workspaces within your organization, you can define them at the GitHub organization level. VS Code automatically detects organization-level custom agents to which your account has access. These agents appear in the agents dropdown alongside built-in, personal, and workspace agents.
Discovery of organization-level custom agents is enabled by default. To stop showing them in chat, set github.copilot.chat.organizationCustomAgents.enabled Open in VS Code Open in VS Code Insiders to false . Learn how to create custom agents for your organization in the GitHub documentation. Harness compatibility The selected agent harness determines which fields and tool names take effect. A shared file location does not imply identical behavior across harnesses.
Local The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . supports the VS Code tool names, subagent configuration, handoffs, and agent-scoped hooks described below. Copilot supports custom agent configuration through its runtime. Use the field-specific guidance below and the Copilot custom agent documentation .
Local handoffs do not apply. See Copilot-specific configuration for fields recognized by the editor but not forwarded during agent conversion. Claude uses its own agent format and runtime behavior. Copilot cloud agent has a separate configuration reference . By default, the selected harness determines the editor's completions, hovers, and validation. Set target: github-copilot to interpret the file with the Copilot schema, or target: vscode to use the Local schema.
The target field overrides file interpretation, not the harness that runs your session. The editor identifies attributes that aren't supported by the effective target. For example, Local doesn't accept skills or mcp-servers , and Copilot doesn't accept handoffs , agents , argument-hint , or advancedOptions . Edit a custom agent file Use completions and hover details in an .agent.md file to choose values for the intended harness.
An explicit target overrides how the editor interprets the file, but doesn't switch your session's harness. For Copilot-assisted editing, set target explicitly when you need target-specific guidance. Without an explicit target, the file context supplied to Copilot describes only shared attributes and doesn't suggest target-specific model or tool values. This differs from normal editor completions, which follow the selected harness.
Hover a value to inspect its details or availability. The editor refreshes validation as harness inventories change. Unknown-value hints depend on discovery completing, so the absence of a hint while discovery is pending doesn't confirm that a value is available. Select the intended harness before editing, then try the agent in that harness to verify its behavior. Editor feedback doesn't replace checking which tools and skills the running agent can use.
See Verify your custom agent . Header fields Fields are optional unless noted. Defaults and harness-specific behavior are listed where applicable. Field Type Description name String The agent's name in the UI. Defaults to the file name. description String What the agent does and when to use it. Required by the Copilot schema. argument-hint String Hint text that describes the input the agent expects. Shown in the Local chat input. advancedOptions Object Local-only map of advanced agent options.
Not supported by the Copilot schema. tools String or array of strings Tools available to the agent. Tool names and supported aliases depend on the harness. User-defined tool sets are deprecated and are not supported in the Copilot harness. See Tools . agents Array of strings Custom agents available as subagents. In Local, use ['*'] or omit the field to allow all available agents, or use [] to prevent subagent use. Include the agent tool set in tools .
See Subagent configuration . model String or array of strings Preferred model or ordered list of alternatives. Selecting the agent uses the first available model. If omitted, the currently selected model is used. Local subagents also use this field as part of their model selection order . model-policy String Whethe
The rest of this page is on the live site.