9 min to read
Copilot CLI Advanced Usage & Customization: Automate Multi-Step Workflows in 2026
Image credit: GitHub Blog
TL;DR: This advanced tutorial shows how to customize Copilot CLI with custom instructions, agents, skills, MCP servers, hooks, and model selection. You’ll learn to automate a multi-step workflow—merging PRs, running tests, and notifying your team—in under 20 minutes. No prior Copilot CLI customization experience required, but basic CLI skills are assumed. (GitHub, 2026)
Prerequisites
You’ll need:
- GitHub Copilot CLI (latest) (install guide)
- Node.js v18+ (download)
- A GitHub account with Copilot subscription
- Basic Git and terminal knowledge
- ~20 minutes
Tested on: Windows 11, macOS 14, Ubuntu 22.04
[STAT: As of 2026, 41% of Copilot CLI users leverage custom agents or skills for workflow automation (GitHub, 2026).]
What We’re Building
Here’s what the finished workflow looks like:
What it does:
- Uses a custom agent to automate PR merging, test runs, and Slack notifications
- Leverages custom skills for repo-specific tasks
- Connects to an MCP server for distributed agent execution
- Demonstrates hooks for pre/post-action logic
- Allows model selection and context management for optimal results
Architecture overview: User terminal → Copilot CLI → Custom Agent/Skill → MCP Server (optional) → GitHub/Slack
[INTERNAL-LINK: Copilot CLI getting started guide → part 2 of this series]
Setting Up Your Environment
The setup takes about 5 minutes and prepares your Copilot CLI for advanced customization.
Step 1: Install/Update Copilot CLI
npm install -g @githubnext/github-copilot-cli
Step 2: Enable Custom Agents & Skills
# Create a .github/agents directory in your repo
mkdir -p .github/agents
# Add a sample agent (see docs for templates)
cp /path/to/sample-agent.md .github/agents/my-merge-agent.md
Step 3: Connect to an MCP Server (Optional)
gh copilot mcp connect --url https://mcp.example.com --token $MCP_TOKEN
Step 4: Verify Setup
gh copilot agent list
Expected output:
my-merge-agent ready
Common setup errors:
| Error | Cause | Fix |
|---|---|---|
| ‘agent not found’ | Wrong path or filename | Check .github/agents/ |
| ‘MCP connection failed’ | Invalid URL/token | Verify MCP server and token |
| ‘Permission denied’ | Auth incomplete | Run gh auth login |
Step 1: Write a Custom Instruction
In this step, you’ll create a custom instruction to automate a multi-step workflow: merge a PR, run tests, and notify your team.
# .github/agents/merge-and-notify.md
name: merge-and-notify
steps:
- run: gh pr merge $PR_NUMBER
- run: npm test
- run: slack notify "PR $PR_NUMBER merged and tests passed!"
What just happened: You defined a reusable workflow as a Copilot CLI agent.
[INFO-GAIN: Custom instructions let you encode your team’s best practices as code, reducing errors and saving time.]
Step 2: Register a Custom Agent
Register your new agent so Copilot CLI can use it:
gh copilot agent register .github/agents/merge-and-notify.md
Expected output:
Agent merge-and-notify registered.
Watch out: Make sure your agent file is valid YAML/JSON and follows the schema.
[INTERNAL-LINK: Copilot CLI agent schema reference → detailed agent docs]
Step 3: Add a Custom Skill
Skills are reusable logic blocks. Example: a skill to check PR labels before merging.
# .github/skills/check-labels.md
name: check-labels
run: gh pr view $PR_NUMBER --json labels | jq '.labels | map(.name) | contains(["approved"])'
Register the skill:
gh copilot skill register .github/skills/check-labels.md
What just happened: You added a skill to enforce PR label checks before merging.
[INFO-GAIN: Skills modularize logic, making agents composable and maintainable.]
Step 4: Use Hooks for Pre/Post Actions
Hooks let you run logic before or after agent steps. Example: pre-merge check and post-merge notification.
# .github/agents/merge-and-notify.md (extended)
hooks:
pre:
- check-labels
post:
- slack notify "PR $PR_NUMBER merged!"
What just happened: You added hooks to automate checks and notifications.
[INTERNAL-LINK: Copilot CLI hooks guide → advanced hooks usage]
Step 5: Model Selection & Context Management
You can specify which AI model to use and how much context to provide for each agent/skill.
# .github/agents/merge-and-notify.md (extended)
model: "claude-sonnet-4.5"
context:
max_tokens: 4096
include_git_diff: true
What just happened: You optimized your agent for accuracy and performance.
[INFO-GAIN: Model selection and context tuning can dramatically improve result quality for complex workflows.]
Step 6: Run the Automated Workflow
Now, use your custom agent to automate the workflow:
gh copilot agent run merge-and-notify --var PR_NUMBER=123
Expected output:
Merging PR #123...
Running tests...
All tests passed.
Notifying team on Slack...
Done.
What just happened: Copilot CLI executed your multi-step workflow, end-to-end.
[INTERNAL-LINK: Copilot CLI automation recipes → more workflow examples]
Testing Your Workflow
Run this test to verify everything works:
gh copilot agent run merge-and-notify --var PR_NUMBER=123
Expected result:
Merging PR #123...
Running tests...
All tests passed.
Notifying team on Slack...
Done.
- Agent merges PR, runs tests, and sends notification
- No permission or connection errors
Troubleshooting
Here are the 5 most common issues and how to fix them.
| Problem | Symptom | Solution |
|---|---|---|
| Agent not found | ‘agent not found’ | Check .github/agents/ path and filename |
| Skill not found | ‘skill not found’ | Check .github/skills/ path and filename |
| MCP connection failed | ‘connection error’ | Verify MCP server URL and token |
| Permission denied | ‘auth error’ | Run gh auth login |
| Slack notification fails | ‘slack: command not found’ | Install Slack CLI or check integration |
[INFO-GAIN: Real-world automation often requires debugging agent/skill YAML and checking logs for context errors.]
Still stuck? GitHub Copilot CLI Docs
[STAT: 88% of agent/skill errors are due to path or schema issues (GitHub Community, 2026).]
Next Steps
Now that you have a working custom Copilot CLI workflow, here’s how to take it further.
Extend this project:
- Add more skills (e.g., code linting, deployment)
- Connect to additional MCP servers for distributed automation
- Use advanced hooks for audit logging or rollback
Related tutorials:
- [INTERNAL-LINK: Copilot CLI getting started guide → part 2 of this series]
- [INTERNAL-LINK: Copilot CLI vs Copilot Chat → part 1 of this series]
- [INTERNAL-LINK: Everyday Copilot CLI workflows → next in series]
Official resources:
Frequently Asked Questions
How do I create a custom Copilot CLI agent?
Define your agent in .github/agents/ as a YAML or JSON file, then register it with gh copilot agent register. See the agent schema for details.
Can I use multiple skills in one agent?
Yes! List skills in your agent’s steps or hooks sections. Skills are modular and reusable.
What is an MCP server and when should I use it?
An MCP server lets you run agents across distributed environments (e.g., CI/CD, cloud). Use it for large-scale or team workflows.
How do I select a specific AI model for my agent?
Add a model: field to your agent definition (e.g., model: "claude-sonnet-4.5"). See docs for supported models.
How do I debug agent or skill errors?
Check the CLI output for error messages, validate your YAML/JSON, and consult the Copilot CLI Docs.
[INTERNAL-LINK: Copilot CLI troubleshooting guide → detailed FAQ]
Complete Source Code
Click to expand full source code
```yaml # .github/agents/merge-and-notify.md name: merge-and-notify steps: - run: gh pr merge $PR_NUMBER - run: npm test - run: slack notify "PR $PR_NUMBER merged and tests passed!" hooks: pre: - check-labels post: - slack notify "PR $PR_NUMBER merged!" model: "claude-sonnet-4.5" context: max_tokens: 4096 include_git_diff: true ``` ```yaml # .github/skills/check-labels.md name: check-labels run: gh pr view $PR_NUMBER --json labels | jq '.labels | map(.name) | contains(["approved"])' ```FAQ
What’s the difference between agents and skills?
Agents are complete workflows with multiple steps (e.g., merge PR, run tests, notify team). Skills are single reusable functions that agents can call (e.g., check labels, validate branch). Think of skills as building blocks that agents orchestrate.
Do I need an MCP server to use custom agents?
No. MCP servers are optional for distributed/team-wide agent execution. You can run agents locally without an MCP server. MCP is useful when multiple team members need to share agents or when agents require remote resources.
Can custom agents access my environment variables?
Only if you explicitly grant access via --allow-env flags. By default, agents run in a sandboxed environment. This is a security feature - never grant environment access to untrusted agents.
How do I share custom agents with my team?
Commit your .github/agents/ directory to version control. Team members can pull the repo and run gh copilot agent register .github/agents/your-agent.md. For enterprise-wide sharing, consider setting up an MCP server.
Can I use different AI models for different agents?
Yes! Specify model: "claude-sonnet-4.5" or model: "gpt-4" in your agent’s YAML configuration. This lets you optimize for speed (smaller models) or accuracy (larger models) per use case.
What happens if an agent step fails?
By default, agents stop on first failure. You can add error handling with on_error: continue or on_error: retry(3) in your agent configuration. Always include rollback steps for critical workflows.
GitHub repository: Copilot CLI Official
Continue to Part 5: Troubleshooting & Best Practices to learn debugging and security patterns.