Developers spend much of their working time in the terminal, generating commands, debugging issues, and running scripts close to their systems. Repeated terminal work tends to pile up small steps such as re-running the same commands, re-explaining context, and translating logs into a form a team can act on. Custom agents in GitHub Copilot CLI address these patterns by turning repeated tasks into reusable workflows.
“A custom agent is a Copilot agent that can be defined using a Markdown file. Instead of relying on generic behavior, you describe how the agent should operate, what tools it can use, what standards it should follow, and what outputs it should produce. The result: its behavior is consistent wherever it runs,” Jacklyn Carroll, Content Writer at GitHub, explained.
How agent profiles work
Custom agents rely on agent profiles, files that live directly inside a repository. Written in Markdown with YAML frontmatter, each profile specifies the agent’s role and area of expertise, the tools it can access, and guardrails that keep outputs consistent. Profile files carry a .agent.md extension, for example accessibility.agent.md, and sit in the .github/agents directory of the target repository.
Because the profile lives in the repository, a team can review it, version it, and share it. The same expectations then follow the work from the CLI into the IDE and into pull requests on GitHub.
Setting up an agent in the CLI
GitHub Copilot CLI runs scripts, calls APIs, and works directly with repositories, which suits agent-driven work. Encoding a workflow once lets a developer invoke it from the terminal, and the agent then executes the same steps every time. A developer runs Copilot CLI, uses the /agent slash command, and selects the agent. The matching profile is the Markdown file with YAML frontmatter placed in the .github/agents directory, defining the agent’s role, scope, capabilities, and guardrails.
Workflows teams can automate
Several workflow patterns suit custom agents, drawn from tasks teams already repeat. A security audit agent runs standard security checks across repositories, groups findings by severity, and outputs a pull request-ready checklist with owners and next steps. An infrastructure as code compliance agent reviews Terraform plans and Kubernetes manifests against organization guardrails, marks risky changes, and produces an approval-ready summary.
A release docs agent gathers merged pull requests since the previous release, categorizes them, drafts release notes in a team’s style, updates the repository’s CHANGELOG.md, and adds a release checklist covering tests, migrations, and rollout and rollback notes. An incident response agent takes a service name and time window, collects first-look data such as recent deploys, error rates, top endpoints, and relevant logs, then drafts an incident report and suggests next steps.
Off-the-shelf and custom options
GitHub offers off-the-shelf agents built with partners including JFrog, Dynatrace, Octopus Deploy, and Arm, covering areas such as observability, infrastructure as code, and security. These agents come with set workflows and tool-specific knowledge, and teams can modify them to fit their own needs.
Custom agents suit teams that want an agent to follow their own naming conventions, review standards, internal tooling, and security checks on every run, and to version that workflow like code.
Getting started begins with installing GitHub Copilot CLI. A common entry point is a task a team repeats each week, turned into an agent that runs the same checks and produces the same reviewable output. A growing set of partner-built agents is available through the Awesome Copilot list, giving teams a way to test the workflow before defining their own.
