One of the most common missteps organizations make when rolling out an AI coding tool is not treating it like any other tool. An organization wouldn't roll out a CI/CD platform for automation, without investing the time in building custom actions, reusable workflows, and other assets to streamline development and enforce policies. The same holds true for AI coding tools. To get the most out of the tool, we need to invest in the infrastructure!

What is AI infrastructure?

AI infrastructure is a broad concept, covering everything from model selection and data pipelines to security controls and observability. But for development teams adopting AI coding tools, one layer tends to get skipped: the context layer — instructions files, custom agents, agent skills, and MCP servers. These are all the tools available to AI coding tools to provide context. They help generate code following our documented practices, while agents perform tasks following our documented guidelines.

At a quick glance, however, determining when to use each can be confusing. After all, at their core, the instructions files, custom agents, and agent skills are primarily defined as Markdown files. And both skills and MCP servers provide context and actions agents can perform.

So, what’s the difference between them? How should we think about incorporating them into our engineering workflows? Let’s explore it all, plus a little bonus “behind the scenes” option with memories.

Working at the edge of what's defined

It’s important to remember that the technology and tooling we’re working with here is nascent. Custom skills, for example, didn’t exist until just a few months ago (from the time of the writing of this blog post). As a result, there’s still quite a bit of exploration to be done on the best approach.

That said, based on my personal experience and in working with customers on their rollout of GitHub Copilot, here’s how I think about these various tools, and how I approach them. As the old saying goes, “If the only tool you have is a hammer, then everything looks like a nail.” Rather than relying solely on skills or instructions files, let’s use each to their strength to create a cohesive approach to our AI infrastructure.

Instructions files

Instructions files are the foundation for providing context to Copilot. They come in two core varieties, copilot-instructions.md and <name>.instructions.md or, as I like to call them, dot instructions files.

copilot-instructions.md is typically stored in the .github folder and provides repository-level guidance that Copilot can apply when working in that repository. It’s perfect for providing project level context, like the folder structure, frameworks being used, and global best practices.

Dot instructions files are typically stored in the .github/instructions folder, and can have an applyTo attribute. The applyTo attribute accepts a glob pattern to identify which files you want the instructions to apply to. To create an instructions file for all Astro files, for example, you’d set the applyTo pattern to **/*.astro. Dot instructions file are built for providing Copilot guidance when working on specific file types. You can use these to provide code snippets and best practices for any file that matches the glob pattern.

Instructions files in action

Instructions files are focused on code generation. If you want to ensure Copilot follows a particular pattern when creating code files, these should be documented in your instructions files.

Every project needs a copilot-instructions.md file that provides an overview of where things are and the core guidelines for code generation. This can include notes about naming conventions, casing, testing requirements, etc. From there, different file types should also be defined. For example, if you’re creating a Flask app, you should have instructions files for our route definitions, for your unit tests, for models if you’re using an ORM, etc.

Copilot can absolutely help create these. In fact, there’s tooling available in VS Code, Copilot CLI, and Copilot cloud agent to help you get started—and you can also browse community examples and templates in Awesome Copilot.

Agent skills

Agent skills are tools in an agent’s toolbox. They guide the agent through a task, like creating a PR, running a test suite, or performing a code review. While they can provide guidance on coding standards and expectations, they can also contain scripts for agents to execute and templates for the agent to use. Skills can be called manually, say with a slash command in Copilot CLI, or dynamically by the agent when it detects a skill is called for.

Skills are defined as folders with the name of the skill, typically inside the .github/skills folder. The entry point is a Markdown file named SKILL.md, which contains two key pieces of information: the name, which should match the name of the folder, and the description, which, as you’d expect, contains the description of the skill. The description also provides guidance to agents on when to call that particular skill.

Skills can also have scripts defined in a scripts subfolder, which empowers the agent to perform tasks, as well as an assets folder, which could contain templates, images, or other resources important to the task at hand.

Agent skills in action

Skills are focused on lower-level tasks. They can be called manually by the user, or automatically by the agent, to orchestrate the steps necessary to perform a higher-level action. I like to think of these as the “verbs,” or the doing aspect to an agent’s work.

I find I iterate on skills more than any of the other options available to me. There are some that are foundational, that I’ll have in every project, like skills on how Copilot should create a PR or manage running test. But as I continue to build, I’ll frequently discover common patterns that I frequently follow, maybe creating a new Svelte component or upgrading particular file types. Those are the moments where I’ll stop and create a new skill.

Custom agents

Custom agents are specialized instances of Copilot agent, defined with Markdown files. They are ideal for operations where specialized background is needed to work successfully, say for managing accessibility, search engine optimization, or upgrading legacy code. Custom agents are defined in Markdown files, typically stored in .github/agents, or can be defined in your GitHub organization.

Beyond just Markdown documentation, you can define the tools the agent is allowed to use, as well as MCP servers it has access to. Taking web accessibility as an example, a custom agent could be defined with access to the necessary end-to-end testing tools to validate its work, as well as the Playwright MCP server that it could use to interact with the site directly.

One key difference between agent skills and custom agents is that custom agents maintain their own context. When a custom agent is started, either directly by the user or by another agent, it begins with the prompt it’s given and builds its context from scratch. This allows it to act independently and eventually report back the results of its work.

Custom agents in action

Custom agents are the higher-level orchestrators. Their primary use case is to look holistically at a problem and determine what needs to be done and how it needs to be done. I like to think of custom agents as the contractor: the entity I call in to manage a complex job, and in turn, manages the work that needs to be done until the job is complete.

I typically iterate on agents. Some will make their plan relatively clear right from the beginning of incorporating Copilot into a project — say accessibility or app modernization. But others will again reveal themselves as you continue to build. Good candidates are tasks where you notice yourself or Copilot needing to call multiple instructions files, update multiple parts of a project, and calling a handful of skills to complete them.

MCP servers

MCP, or Model Context Protocol, is an open standard to allow AI agents to communicate with external systems. Through MCP, you can give an agent access to documentation, assets, and other server-based tools. MCP servers can be used to perform actions on your behalf like creating an issue on GitHub, retrieving data from a database, or interacting with your cloud.

One great example of an MCP server is Playwright server. Playwright is an end-to-end web testing tool. With the Playwright MCP server, Copilot can interact with a website, performing operations as a user, evaluating HTML, CSS and JavaScript, and even taking screenshots. Through this, it can validate the code it generated or even walk through repro steps to track down the root cause of a reported bug.

MCP servers in action

The key benefit of an MCP server is access to external resources, be it actions or data. On the information side, you can use MCP servers to bridge the gap between an LLM’s training data and today or to access information about your internal libraries and documentation. On the operations side, MCP servers can be called to create cloud resources, manage issues, or work with databases.

The first thing I recommend is to add MCP servers with documentation for any of the frameworks in use in your project. Next is any external services you frequently need to access, like your data or cloud providers, or other resources. GitHub also hosts a registry of MCP servers.

Everything in harmony

At first glance, there appears to be a lot of overlap in everything we’ve discussed, especially since instructions files, agent skills, and custom agents are all primarily based in Markdown files. And there aren’t necessarily any hard and fast rules about exactly how to use each of the options available to you.

That said, having a clearly defined approach will ensure consistency, making it easier for your team to manage your AI infrastructure. This in turn will help Copilot generate the code you need, perform the required tasks, and following your organization’s best practices. Here’s how I approach things, from top to bottom.

• Custom agents are the orchestrators. These are for the big jobs, where multiple operations fall under one umbrella. Examples include agents for accessibility, upgrading legacy code, and debugging applications. These agents will call the skills, work with the MCP servers, and reference the instructions files necessary to complete the job.

• Agent skills are the task masters. These are limited to one specific operation but are optimized exactly for that. Examples include running tests, creating pull requests, and creating components.

• MCP servers are the external helpline. They provide access to the “everything else” necessary to perform the task. Examples include documentation, issues, and cloud resources.

• Instructions files are the code cheat sheets. They provide details of what the code should look like and the practices that need to be followed. Examples include samples of what the code should look like, a list of best practices, and pitfalls to be avoided.

By having a clearly defined structure, you can avoid having to make constant decisions about how to manage your AI infrastructure, which will leading to increased consistency. It’ll also provide your developers and Copilot the foundation from which to build.

To begin building out your own AI infrastructure, a great place to start is awesome-copilot, a community-contributed collection of instructions, agents, skills, and other assets to help you get the most out of GitHub Copilot. As you turn those examples into your own standards, the repository custom instructions guide provides a starter prompt for further customization. The GitHub MCP Registry helps you discover MCP servers that connect Copilot to external tools and the Copilot customization cheat sheet offers a quick reference for the available customization options.