A repository already has house rules - how it is structured, what things are called, which command actually runs the tests. The trick is to write them down where the agent can read them, instead of retyping them into every prompt. GitHub’s beginner walkthrough of the Copilot app organises this into four layers you commit to the repository, plus MCP servers for reach.

Key facts

Fact Detail
Question answered How do I teach GitHub Copilot my project’s conventions?
Short answer Put the conventions in the repository instead of in your prompt.
Reading time ~3 min
Last updated 2026-10-13

The four layers, and what each is for

  • Custom instructions - a repository-wide file, .github/copilot-instructions.md. Architecture in a paragraph, the package manager, how to run the tests. Add this layer first, because it shapes almost every task.
  • File-scoped instructions - .github/instructions/ with an applyTo field (for example **/*.tsx). These keep a convention attached to the part of the tree it belongs to, so front-end rules never leak into build scripts.
  • Agent skills - .github/skills/<name>/SKILL.md. A skill is a procedure loaded when it is relevant, and it can carry its own instructions and resources. Use it for the sequence you repeat, not the fact you restate.
  • Custom agents - .github/agents/. A profile for work that is larger than one procedure and spans files: what it exists for, which instructions apply, which tools it may use. A review that has to look at components, templates, styles and interactions is the kind of job this is for.
  • MCP servers - reach beyond the repository. A documentation server is the simple case; Playwright is the interesting one, because it lets Copilot open the running application in a browser and check that the interface behaves the way the change claims.

The post is by GitHub’s Christopher Harrison and was published on 2026-10-12 (https://github.blog/ai-and-ml/github-copilot/github-copilot-app-for-beginners-how-to-teach-copilot-about-your-codebase/). What makes it worth reading is the placement: none of this goes in the prompt.

The part worth copying even if you do not use Copilot

The four layers are the details; the habit underneath them is portable. Other agents use their own instruction files, but the move is identical - put the project’s rules in the project, once, and let every task inherit them.

That habit pays off most with a desktop agent, which works on your real files rather than a copy in a browser tab. Rules that live in the repository are the difference between an agent that improvises your conventions and one that follows them. Two habits make it work in practice: describe one convention at a time, and check on the next task whether it was actually applied. If it was not, the rule is usually too vague or buried too deep - that is the signal to tighten it, not to add more.

A short checklist for a first pass

  1. Pick the convention you explain most often: the test command, a naming rule, a folder that must not be touched.
  2. Commit it to .github/copilot-instructions.md (or your agent’s equivalent file).
  3. Run a normal task and check whether it was applied.
  4. Only when a rule is really a procedure does it become a skill; only when the work spans many files does it become a custom agent.
  5. Look at GitHub’s Awesome Copilot collection for ready-made examples, and adapt them to your project rather than pasting them in.

If you want the same pattern in a desktop agent on Windows - rules the agent reads before it touches your files, and approval before any command runs - that is the workflow MOOGH provides. You can get it at https://agent.aimoogh.com/download and see how a project’s own context shapes what the agent does.

Related reading: