GitHub Copilot CLI Lets Teams Build Custom AI Agents From Markdown Files

GitHub Copilot CLI has long been useful for one-off terminal tasks: generating commands, debugging scripts, querying your repo. But every time you started a new session, you started from scratch. Your team's conventions, tooling preferences, and output standards had to be re-explained from scratch. Custom agents fix that.

A custom agent is a Copilot agent 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.

Prompts as code

Custom agents are defined using agent profiles that live directly in your repository. The agent profile is a Markdown file with YAML frontmatter that defines the agent's role, scope, capabilities, and guardrails. The agent profile file ends with .agent.md, for example accessibility.agent.md. The Markdown body is where you write the actual instructions: what the agent knows, what it should check for, and what format it should output.

Here is what a minimal agent profile looks like:

---
name: Security Auditor
description: Runs standard security checks and outputs a PR-ready checklist.
model: GPT-4.1
tools: ['gh', 'git', 'semgrep', 'trivy', 'gitleaks', 'jq']
---
You are a security auditor. For each repo provided, run secret scanning,
container scanning, and SAST. Group findings by severity (Critical, High,
Medium, Low) and output a checklist with owners and next steps.