{"meta":{"title":"About custom agents","intro":"Custom agents enhance Copilot with assistance tailored to your needs.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/concepts","title":"Concepts"},{"href":"/en/copilot/concepts/agents","title":"Agents"},{"href":"/en/copilot/concepts/agents/cloud-agent","title":"Cloud agent"},{"href":"/en/copilot/concepts/agents/cloud-agent/about-custom-agents","title":"Custom agents"}],"documentType":"article"},"body":"# About custom agents\n\nCustom agents enhance Copilot with assistance tailored to your needs.\n\n## About custom agents\n\nCustom agents are specialized versions of the Copilot agent that you can tailor to your unique workflows, coding conventions, and use cases. They act like tailored teammates that follow your standards, use the right tools, and implement team-specific practices. You define these agents once instead of repeatedly providing the same instructions and context.\n\nYou define custom agents using Markdown files called agent profiles. These files specify prompts, tools, and MCP servers. This allows you to encode your conventions, frameworks, and desired outcomes directly into Copilot.\n\nThe agent profile defines the custom agent's behavior. When you assign the agent to a task or issue, it instantiates the custom agent.\n\n## Agent profile format\n\nAgent profiles are Markdown files with YAML frontmatter. In their simplest form, they include:\n\n* **Name** (optional): A display name for the custom agent. If omitted, the agent's filename is used as its identifier and default display name.\n* **Description**: Explains the agent's purpose and capabilities.\n* **Prompt**: Custom instructions that define the agent's behavior and expertise.\n* **Tools** (optional): Specific tools the agent can access. By default, agents can access all available tools, including built-in tools, and MCP server tools.\n\nAgent profiles can also include MCP server configurations using the `mcp-servers` property.\n\n### Example agent profile\n\nThis example is a basic agent profile with name, description, and prompt configured.\n\n```text\n---\nname: readme-creator\ndescription: Agent specializing in creating and improving README files\n---\n\nYou are a documentation specialist focused on README files. Your scope is limited to README files or other related documentation files only - do not modify or analyze code files.\n\nFocus on the following instructions:\n- Create and update README.md files with clear project descriptions\n- Structure README sections logically: overview, installation, usage, contributing\n- Write scannable content with proper headings and formatting\n- Add appropriate badges, links, and navigation elements\n- Use relative links (e.g., `docs/CONTRIBUTING.md`) instead of absolute URLs for files within the repository\n- Make links descriptive and add alt text to images\n```\n\n## Where you can configure custom agents\n\nYou can define agent profiles at different levels:\n\n* **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents.\n* **Organization level**: Create `/agents/CUSTOM-AGENT-NAME.md` in the organization's `.github` or `.github-private` repository for broader availability within the organization.\n* **Enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in the `.github-private` repository of an organization that an enterprise owner has designated in enterprise settings for availability across all repositories in the enterprise.\n\nFor more information, see [Preparing to use custom agents in your organization](/en/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [Preparing to use custom agents in your enterprise](/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).\n\n## Where you can use custom agents\n\n> \\[!NOTE]\n> Custom agents are in public preview for JetBrains IDEs, Eclipse, and Xcode, and subject to change.\n\nOnce you create custom agents, they become available to:\n\n* **Copilot cloud agent on GitHub.com**: The agents tab and panel, issue assignment, and pull requests\n* **Copilot cloud agent in IDEs**: Visual Studio Code, JetBrains IDEs, Eclipse, and Xcode\n* **GitHub Copilot CLI**\n\nYou can use agent profiles directly in Visual Studio Code, JetBrains IDEs, Eclipse, and Xcode. Some properties may function differently or be ignored between environments.\n\nFor more information on using custom agents in Visual Studio Code, see [Custom agents in VS Code](https://code.visualstudio.com/docs/copilot/customization/custom-agents).\n\n## Next steps\n\nTo create your own custom agents, see:\n\n* [Creating custom agents for Copilot cloud agent](/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents)\n* [Creating and using custom agents for GitHub Copilot CLI](/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)\n* [Copilot customization cheat sheet](/en/copilot/reference/customization-cheat-sheet)"}