GitHub Copilot CLI Custom Agents and Skills

If you want GitHub Copilot CLI custom agents to be useful instead of chaotic, you need to separate three things that sound similar but behave very differently: custom instructions, skills, and custom agents. Instructions tell Copilot how your repo works in general. Skills teach it a repeatable workflow that should load just in time. Custom agents define a specialist persona with its own profile, tools, and operating style.

Heads up: GitHub Copilot CLI moves fast. It went GA in February 2026 and ships updates constantly, so commands, flags, file locations, and customization behavior change often. Everything here was verified against the CLI as of July 2026 -- always check the official GitHub Copilot CLI docs for the very latest.

Think about it this way: custom instructions are the house rules, Copilot CLI skills are playbooks, and custom agents are specialized teammates. You can use all three together, but they solve different problems.

GitHub Copilot CLI Custom Agents vs Instructions vs Skills

The official GitHub docs describe Copilot CLI customization as a layered system. Custom instructions tell Copilot how to behave in general. Skills tell Copilot how to perform a specific kind of task. Custom agents give Copilot a specialized agent profile that can be selected, inferred, or invoked from the command line.

That sounds abstract, so here is the decision framework I use when evaluating GitHub Copilot CLI custom agents and related extensibility:

The tradeoff is context versus specificity. If you put everything in always-on instructions, Copilot sees it every time. If you hide standards in a skill, Copilot may not use them for ordinary changes. If you create a custom agent for every tiny preference, your agent list becomes noisy. This maps well to broader agent design in Microsoft Agent Framework in C#: keep durable policy separate from task-specific orchestration.

Custom Instructions: The Always-On Layer for GitHub Copilot CLI Custom Agents

Custom instructions are where I would start before creating any GitHub Copilot CLI custom agents. They are simple, durable guidance that Copilot CLI loads automatically for repository or user context. The official custom instructions documentation currently lists several supported sources.

For repository-wide guidance, use .github/copilot-instructions.md. For cross-agent instructions, use AGENTS.md in the repository root or current working directory. Copilot CLI also reads CLAUDE.md and GEMINI.md from the repository root, which is useful if your team wants one convention file to work across more than one coding agent. User-local instructions can live at ~/.copilot/copilot-instructions.md.

The important behavior is that instructions are combined. If Copilot CLI finds both AGENTS.md and .github/copilot-instructions.md at the repository root, both are used. For path-specific instructions, .github/instructions/NAME.instructions.md files can include applyTo frontmatter so guidance applies only when matching files are involved.

# AGENTS.md

## Repository rules

- Use file-scoped namespaces for all C# files.
- Add tests for non-trivial behavior changes.
- Run the smallest targeted `dotnet test` command that covers the change.
- Do not modify public API contracts without calling out the tradeoff.

That is intentionally boring. Good custom instructions should be boring. They should encode stable expectations, not a full workflow manual.

You can initialize custom instructions with the current copilot init command. The command reference documents copilot init as the way to initialize Copilot custom instructions for a repository.

# Create starter custom instructions for the current repository.
copilot init

Use custom instructions when the guidance should apply to most Copilot CLI sessions: test naming, preferred package manager, architecture boundaries, documentation rules, commit discipline, and validation expectations. Do not use them for a migration checklist that only matters twice a year. That belongs in a Copilot CLI skill.

Copilot CLI Skills: Just-In-Time Workflows with SKILL.md

A Copilot CLI skill is a folder with a required SKILL.md file. The current docs describe skills as folders of instructions, scripts, and resources that Copilot can load when relevant. Project skills can live under .github/skills/, .claude/skills/, or .agents/skills/. Personal skills can live under ~/.copilot/skills/ or ~/.agents/skills/.

For this guide, the most important paths are the Copilot CLI paths you will likely use first:

.github/skills/<skill-name>/SKILL.md
~/.copilot/skills/<skill-name>/SKILL.md

The SKILL.md file uses YAML frontmatter. The required fields are name and description. The license field is optional. The docs also show allowed-tools as an optional frontmatter field when a skill needs to run scripts, but this deserves caution. Pre-approving shell access changes the risk profile of a skill, especially if the skill or its support scripts came from outside your organization.

Here is a practical SKILL.md example for a .NET test workflow:

---
name: dotnet-test-writer
description: Writes focused .NET tests before implementation. Use when asked to add or fix behavior in a C# project.
---

When this skill is used, follow this workflow:

1. Inspect the existing test project structure before writing code.
2. Add a failing xUnit test that describes the desired behavior.
3. Run the smallest targeted `dotnet test` command that should fail.
4. Implement the minimal production change.
5. Re-run the same targeted test and summarize the result.

Prefer deterministic tests. Use mocks only when they make the test boundary clearer.

That is a good Copilot CLI skill because it captures a repeatable process. It does not need to be loaded for every question about a repository. It should show up when the task is about writing tests.

You can also include scripts or resources next to the skill file. The agent skills documentation states that Copilot automatically discovers files in the skill directory and makes them available alongside the skill instructions. That means a skill can include a validation script, a checklist, an example output format, or a template.

.github/skills/dotnet-test-writer/
├── SKILL.md
└── run-targeted-tests.ps1

If you add a skill during an interactive Copilot CLI session, use /skills reload. You can list skills with /skills list, inspect a specific one with /skills info, and add alternate skill locations with /skills add. The command reference also documents copilot skill as a terminal subcommand for list, add, and remove operations outside an interactive session.

The MOFU decision point is this: choose Copilot CLI skills when you want a repeatable workflow, not a permanent persona. If the workflow says "when doing release notes, use this format," that is a skill. If it says "be a senior release engineer with these tools and this judgment model," that starts to look like a custom agent.

Custom Agents: Specialized .agent.md Profiles for Copilot CLI

Custom agents are where GitHub Copilot CLI custom agents become genuinely interesting. A custom agent is a specialized version of Copilot defined by an .agent.md file. The current docs say repository-level agents live in .github/agents/, while user-level agents live in ~/.copilot/agents/. The agent file name matters because programmatic invocation uses the file name without .agent.md.

.github/agents/security-auditor.agent.md
~/.copilot/agents/dotnet-test-writer.agent.md

Custom agents can be created interactively with /agent, or manually by adding the Markdown file yourself. The official custom agents documentation currently documents these use patterns: choose an agent with /agent, ask Copilot to use a named agent in natural language, let Copilot infer the agent from the task, or run it programmatically with --agent.

# Interactive selection inside Copilot CLI.
/agent

# Programmatic custom agent invocation.
copilot --agent security-auditor --prompt "Review src/Auth for high-confidence security issues"

A .agent.md file has YAML frontmatter followed by the agent's system-style instructions. The configuration reference lists fields such as name, required description, tools, model, disable-model-invocation, user-invocable, and mcp-servers. You do not need all of those for a useful first agent.

Here is a concrete security auditor example:

---
name: security-auditor
description: Reviews code for high-confidence security issues. Use for security review, auth review, injection risk, secret exposure, or dependency risk.
tools: ["read", "search"]
disable-model-invocation: false
---

You are a security auditor for application code.

Focus on exploitable issues, not style. Prioritize authentication bypass, authorization gaps, injection, unsafe deserialization, secret exposure, cryptography misuse, and vulnerable dependency patterns.

Do not edit files. Report findings with severity, confidence, affected file path, why the issue is exploitable, and the smallest safe remediation.

If evidence is insufficient, say so clearly instead of speculating.

Notice the tools boundary. This agent can read and search, but not edit or execute. That is exactly the point. A security auditor should not need to rewrite code unless you explicitly want a remediation agent.

Custom agents can also reference MCP servers and MCP tools in their configuration. I would keep that scoped and deliberate. MCP configuration is a separate topic, but the short version is that a custom agent can be given access to external tools when its role needs them. For example, a documentation agent might use a docs-search MCP tool, while a security agent might use a dependency intelligence tool. Do not add broad MCP access just because the option exists.

For deeper agent design patterns, Advanced GitHub Copilot SDK in C#: Tools, Hooks, Multi-Model, Multi-Agent maps well to the same tool and delegation tradeoffs.

When to Use Which Copilot Extensibility Layer

The easiest mistake is to turn every good instruction into every extensibility mechanism. You do not need an AGENTS.md rule, a SKILL.md workflow, and a .agent.md profile all saying "write tests" in slightly different ways. That creates conflicts and makes behavior harder to explain.

Use custom instructions when the rule is stable and broadly applicable. A repository that requires immutable domain models, specific test naming, or a particular package manager should encode that in instructions. The upside is consistency. The downside is that too much always-on text can distract the agent from the immediate task.

Use Copilot CLI skills when the workflow is repeatable but situational. A release-note generator, benchmark runner, migration checklist, accessibility review process, or incident summary format can all be skills. The upside is just-in-time context. The downside is that a skill is still instructions, not a separate specialist with an isolated context window.

Use GitHub Copilot CLI custom agents when the work benefits from specialization, delegation, or a distinct tool boundary. A security auditor, test writer, documentation reviewer, performance investigator, or API designer can be a custom agent. The upside is clearer role separation. The downside is more configuration to govern and test.

Here is the practical comparison:

This is the same discipline I recommend when building custom agent systems in code. If you are building an AI-powered CLI yourself, Build an AI CLI Developer Tool with GitHub Copilot SDK in C# shows the product-building side of the problem. If you are configuring Copilot CLI, you are choosing the right built-in extension layer.

How Skills and Custom Agents Work Together

Skills and custom agents are not mutually exclusive, but avoid duplication. Let the custom agent define the persona and tool boundary. Let the skill define the repeatable workflow. Let custom instructions define durable repository rules.

For example, AGENTS.md might say all non-trivial changes require tests. A dotnet-test-writer skill can define the red-green workflow. A dotnet-test-writer.agent.md profile can allow read, search, edit, and execute tools while staying focused on test work. A security-auditor.agent.md profile can stay read-only and focused on high-confidence findings.

This matters because vague boundaries create vague agent behavior. A layered Copilot CLI setup gives the agent less to invent and gives you more predictable review points. The evaluation mindset from Evaluating AI Agents with Microsoft.Extensions.AI.Evaluation in C# applies here too: test your agents with representative prompts before trusting them in important workflows.

Hooks and Plugins: The Brief Pointer

Hooks and plugins are adjacent to GitHub Copilot CLI custom agents, but they are not the main focus of this article.

Hooks run shell commands at lifecycle points such as sessionStart, sessionEnd, preToolUse, postToolUse, userPromptSubmitted, agentStop, and subagentStop. They are useful when you need policy, logging, or automation around agent activity. For example, a preToolUse hook could warn before certain paths are edited, while a sessionEnd hook could archive a transcript.

Plugins package customization. The official comparison docs describe plugins as installable bundles that can include skills, hooks, custom agents, and MCP server configurations. Use plugins when you want distribution and updates across a team, not when you are experimenting with one local SKILL.md file.

I would evaluate hooks and plugins after you have the first three layers under control. Start with instructions, then skills, then custom agents. Add hooks when prompting is not enough. Add plugins when distribution becomes the problem.

Common Pitfalls with GitHub Copilot CLI Custom Agents

The biggest pitfall is using the wrong layer because it is available. Do not put volatile command sequences into always-on instructions. Do not create a custom agent for a simple checklist. Do not give every custom agent all tools by default. A reviewer often needs read and search. A test writer may need edit and execute. The tool list should match the job.

Also review community skills and plugins before using them. Skills can include scripts, and allowed-tools can pre-approve tool usage. That is a trust decision, not just a convenience setting.

A Practical Adoption Path for a .NET Team

For a .NET team, I would start small: one instruction file, one high-value skill, and one constrained custom agent. Put durable rules in AGENTS.md or .github/copilot-instructions.md: build commands, test expectations, C# conventions, and repository constraints.

Then create one skill for a workflow you repeat often, such as test writing, release notes, migration validation, or GitHub Actions debugging. After that, create one custom agent with a clear boundary. A read-only security auditor is a strong first candidate because it demonstrates specialization without edit risk.

Finally, evaluate with real prompts. Invoke the custom agent with /agent, compare output with and without it, and check whether review effort drops. The goal is less repeated steering with more predictable output.

Wrapping Up: Use the Smallest Layer That Solves the Problem

GitHub Copilot CLI gives you several customization layers, and the best choice depends on the job. Use custom instructions for always-on repository standards. Use Copilot CLI skills for repeatable workflows that should load just in time. Use GitHub Copilot CLI custom agents when you need a specialist persona, scoped tools, and optionally MCP-backed capabilities.

The deeper lesson is not specific to Copilot. Agentic systems work better when you separate policy, workflow, tools, and roles. Copilot CLI now gives you those seams in the terminal. Use them deliberately, validate them with real tasks, and keep the configuration small enough that your team can reason about it.

FAQ

Are GitHub Copilot CLI custom agents the same as skills?

No. GitHub Copilot CLI custom agents are specialized agent profiles, usually defined in .agent.md files, with descriptions, instructions, and optional tool constraints. Skills are SKILL.md workflows that Copilot loads when relevant. A custom agent is closer to a specialist teammate. A skill is closer to a task playbook.

Where do I put a .agent.md file for Copilot CLI?

For repository-level custom agents, put the file under .github/agents/. For personal custom agents shared across projects, put it under ~/.copilot/agents/. The file should use the .agent.md extension, such as .github/agents/security-auditor.agent.md.

Where do I put a Copilot SKILL.md file?

For project skills, use a folder under .github/skills/, such as .github/skills/dotnet-test-writer/SKILL.md. For personal skills, use ~/.copilot/skills/<skill-name>/SKILL.md. The file name must be exactly SKILL.md, and the skill folder name should be lowercase with hyphens.

Should I use AGENTS.md or .github/copilot-instructions.md?

Use either or both, depending on your team. AGENTS.md is useful for cross-agent instructions that multiple coding agents can read. .github/copilot-instructions.md is GitHub Copilot-specific repository guidance. Copilot CLI can combine both when they exist, so avoid conflicting instructions.

How do I invoke a custom agent in Copilot CLI?

In an interactive session, use /agent and select the custom agent. You can also ask Copilot to use a named agent in plain language, or run it programmatically with copilot --agent security-auditor --prompt "Review src/Auth". The --agent value usually matches the .agent.md file name without the extension.

When should I avoid creating a custom agent?

Avoid a custom agent when a short instruction or a skill is enough. If the behavior should apply to every task, use custom instructions. If the behavior is a repeatable workflow but does not need a separate persona or tool boundary, use a skill. Custom agents fit better when specialization and delegation matter.

Can custom agents use MCP servers?

Yes, custom agent configuration can reference MCP servers and MCP tools. Keep that scoped to the agent's real job. MCP expands what an agent can do, so it should be treated as a capability decision rather than a default setting.