Instructions, Prompts, Skills, and Custom Agents in GitHub Copilot Agent Mode
Note: This blog is a personal notebook. I write it to record what I work on, for my own reference, not to publish it on social media or to promote myself. If a post is still useful to you, I am glad, but that is not why it exists.
This post was published on December 18, 2025. Software versions, product features, links, and tool availability may have changed since then. Always check official documentation for the latest information. Some screenshots show small details. Zoom in on the page to see them clearly.
GitHub Copilot in VS Code is more than a chat box. In Agent Mode, four customization layers control how it works: custom instructions, prompt files, skills, and custom agents. Most teams do not need more AI. They need the right setup for the way they work.
Problem
Many people use Agent Mode the same way: one long prompt, too much context, no clear boundaries, and a late review. They use the wrong feature for the task.
Why this matters
The four layers solve different problems. If you mix them, Agent Mode becomes noisy. Keep them separate, and you get consistent output, better reuse, and safer tool access.
Architecture
Think of a football team. Instructions are the rules of the game. A prompt file is a set piece you call when needed. A skill is a trained routine. A custom agent is a position: only the goalkeeper may use hands.
| Layer | Best use | How it behaves |
|---|---|---|
| Custom instructions | Project rules and conventions; stored as .github/copilot-instructions.md, *.instructions.md, or AGENTS.md. |
Applied automatically or by matching file/task context. |
| Prompt files | Reusable tasks such as test generation, review, refactoring, or docs; stored as .prompt.md files. |
Invoked manually, usually through / commands in chat. |
| Skills | Portable workflows with instructions, scripts, examples, and resources in a SKILL.md-based folder. |
Loaded when relevant or run as slash commands. |
| Custom agents | A specialized role with its own model, tools, MCP servers, and handoffs; authored as .agent.md. |
Selected as the active agent or used as a subagent. |
Note: AGENTS.md is an always-active instruction file, not a custom agent.
The session adds boundaries: where the agent runs, how much autonomy it has, and which tools or MCP servers it can use. Ask what the workflow may do, not how much context you can give it.
Demo steps
Set up one layer at a time.
1. Custom instructions
Create .github/copilot-instructions.md with the rules for every request: naming, error handling, test-first behavior, and documentation style. VS Code applies it automatically, and file-scoped *.instructions.md rules can target folders or file types. A simple AL instruction:
Always generate AL tests before implementation for business rules. Use descriptive test names, avoid hidden side effects, and prefer small codeunits.
2. Prompt files
Create a prompt file when the task repeats but the context changes. You start it manually. This example runs as /write-discount-tests:
Generate AL tests for a discount rule using the current codeunit and return only the test codeunit.
3. Skills
Create a skill when the task needs more than text: scripts, examples, and resources. A skill named al-test-review can hold a SKILL.md file, a checklist, and example test patterns.
4. Custom agents
Create a custom agent with /create-agent when a workflow needs its own role and tool boundary. A “BC Architect” agent can review architecture with codebase search, avoid large write operations, and hand the implementation to another agent.
Scope
This model is simplified. It leaves out the settings flags and the special cases in local, background, and cloud sessions. It assumes that your team separates stable conventions, reusable tasks, and higher-trust workflows.
Risks and limits
More customization does not always give a better result. VS Code combines multiple instruction files in no guaranteed order. Instructions do not change inline suggestions. Prompt files and agents still depend on the quality of your request.
Skills and MCP increase power and risk together: skills bring scripts into the workflow, and MCP gives access to external tools and data. Review discipline and tool boundaries matter more as capability grows.
Next iteration
- Start with one workspace instruction file for the stable rules.
- Turn the multi-step prompts you repeat into prompt files.
- Create one or two skills for workflows that need examples or scripts.
- Add custom agents only when a role needs different tools, permissions, or MCP access.
Closing note
Your workflow tells you which layer to use: instructions for rules, prompts for repeated tasks, skills for deeper workflows, and custom agents for separate roles.