Skip to content
eWiki The practical AI reference

AI Basics

How to Use GitHub Copilot Custom Instructions for Repository-Specific Guidance

Small stacks of white cards with faint grid sketches arranged on a desk beside a blue binder clip and black fountain pen.

GitHub Copilot custom instructions let you store reusable project guidance in your repository. Start with a repository-wide Markdown file for shared standards, add targeted files for narrower rules, and verify how your chosen Copilot environment discovers and applies them.

Create repository-wide GitHub Copilot instructions

Create .github/copilot-instructions.md at the repository root to provide guidance across Copilot sessions for that project. Write the file in Markdown and keep it focused on project-level context and standards that would otherwise need to be repeated in individual prompts.

Useful subjects include the technology stack, coding style, naming conventions, preferred libraries, architectural patterns, security requirements, error-handling practices, and documentation standards. The file can also state the build, test, and validation requirements Copilot should follow during coding tasks.

Make each instruction concrete and actionable. For example, name the repository’s required test or validation process instead of merely asking Copilot to “check the code.” Keep broadly applicable rules here; specialized requirements for a language, directory, file type, or task belong in targeted instruction files.

Three stacks of cards showing hand-drawn box-and-arrow diagrams, with a black pen and metal ruler on a white desk.

Add path-specific rules with .instructions.md files

Use path-specific instructions when a rule should apply only to particular files or tasks. These files have names ending in .instructions.md and are stored within or below .github/instructions.

A targeted file can contain an applyTo frontmatter value with glob patterns defining the files that receive its guidance. This allows a team to separate repository-wide standards from rules intended for a specific language, file type, or directory. It also reduces the chance that specialized guidance will be applied too broadly.

When a file matches path-specific instructions and repository-wide instructions are also present, GitHub’s IDE documentation says both sets are used. Keep the two layers compatible: place shared project standards in .github/copilot-instructions.md, then use narrowly scoped files for exceptions or additional requirements. In Copilot CLI, modular instruction files apply only when their applyTo pattern matches a file being worked on.

A person in a blue sweater writes in an open notebook at a desk with a keyboard, lamp, mug, books, and computer monitors.

Check discovery rules in VS Code and Copilot CLI

Instruction discovery is not identical across every Copilot environment. In VS Code, first select the intended agent harness, because supported formats and discovery behavior depend on that choice. For Local harness sessions, documented project formats include .github/copilot-instructions.md, AGENTS.md, and CLAUDE.md. Targeted guidance can use .github/instructions/**/*.instructions.md or Markdown files under .claude/rules.

Depending on the supported format and harness, targeted instructions may be activated by a matching file pattern, relevance to the task, or manual attachment. GitHub’s IDE documentation also allows multiple AGENTS.md files in a repository and says the nearest one in the directory tree takes precedence while Copilot works.

Copilot CLI discovers repository and agent instructions in standard locations along the relevant directory path. Run /instructions to see the files discovered for the current session and enable or disable individual files. The CLI can combine multiple applicable user-level and repository files and remove some identical duplicates, but it does not define a general precedence order among them. Avoid contradictory rules rather than relying on one file to override another.

Finally, do not expect these instructions to control every Copilot feature: VS Code documentation states that custom instructions are not considered for inline suggestions displayed while you type.

Conclusion

A practical setup begins with shared project standards in .github/copilot-instructions.md, followed by narrowly scoped .instructions.md files only where specialized guidance is necessary. Keep overlapping files consistent, select the agent harness your team intends to use, and inspect the instructions discovered in that environment before depending on them.

As a next step, create one focused repository-wide file, add path-specific rules only for a clearly defined need, and use the available discovery controls—such as Copilot CLI’s /instructions command—to confirm that the expected guidance is active.

Disclosures and limitations

  • This article was prepared with AI assistance and synthesized only from the supplied GitHub and VS Code documentation records; it does not report hands-on testing or personal product use.
  • No product recommendation, pricing claim, or affiliate offer is included. Readers should independently check for affiliate relationships before acting on links or recommendations added elsewhere.

Sources

Improve this guide

Report a problem or suggest the next question

Submissions enter a private editorial queue. They are reviewed and deduplicated before any public update or new page is created.