Part 7 Copilot Configuration

This page covers how to create, maintain, and share GitHub Copilot custom instructions across projects. Custom instructions give GitHub Copilot project-specific context, so every response is aligned with your conventions without repeating guidance in every prompt.

For hands-on walkthroughs with GitHub Copilot and AI-assisted coding, see the Part 6 AI as a Learning Companion page. For practical discoveries about copilot-instructions.md in wiki repositories, see the Part 8 Field Notes page.

Adding copilot-instructions.md to your repository

A copilot-instructions.md file gives GitHub Copilot project-specific context every time it works with your repository. Instead of repeating the same guidance in every prompt, you define your conventions once and GitHub Copilot follows them automatically. This walkthrough guides you through creating and maintaining this file.

What copilot-instructions.md does

The copilot-instructions.md file is a Markdown file stored at .github/copilot-instructions.md in your repository. When GitHub Copilot processes requests in Visual Studio Code, it reads this file and applies the instructions as additional context. This means every response GitHub Copilot gives is already aligned with your project's standards - without you having to specify them each time.

Common instructions include:

• Coding conventions - Naming patterns, formatting rules, and preferred cmdlets or modules
• Project structure - Where files go, how folders are organized, and naming patterns for new files
• Documentation standards - Comment styles, header formats, and required metadata in scripts
• Security requirements - Authentication patterns, credential handling, and compliance rules
• Writing style - Tone, terminology, and formatting rules for documentation and wiki pages

Creating the file

Follow these steps to add a copilot-instructions.md file to your repository:

Note

Earlier versions of the GitHub Copilot extension included a UI panel where you could click Add repository instructions to auto-create this file. That panel was removed when GitHub consolidated Copilot features into the current Copilot Chat experience. The file is still fully supported - you just create it manually now.

1. In Visual Studio Code, create the folder and file:

    📂 your-repository/
     └─ 📂 .github/
         └─ 📄 copilot-instructions.md
   

2. Open Copilot Chat and ask for help drafting the initial content:

   Please help me draft a copilot-instructions.md file for my PowerShell project.
   The file should include sections for coding conventions, project structure, and
   documentation standards. My scripts follow these conventions: verb-noun naming
   for functions, comment-based help on all functions, and CIM instances instead
   of WMI.
   

3. Review the generated draft carefully - this file shapes every future GitHub Copilot interaction in your repository, so it is worth getting right

4. Start simple. A good first version covers coding conventions, script headers, and documentation standards in short bullet lists. Here is an example structure:

   • A top-level heading like # Copilot Instructions
   • A ## Coding conventions section with rules such as: use approved PowerShell verbs for function names (e.g., Get-, Set-, New-), use Get-CimInstance instead of Get-WmiObject, include comment-based help on all functions, and use PascalCase for function names
   • A ## Script header section specifying that all scripts must include a description comment and an elevation requirement comment
   • A ## Documentation section with rules like: use Markdown for all documentation, write in a professional but approachable tone, and use sentence case for headings

5. Commit the file to your repository so it is available on every device where you clone the project

Note

The copilot-instructions.md file is read automatically by GitHub Copilot when you work in the repository. There is no additional configuration needed - just create the file in the .github/ folder and commit it. For wiki repositories, there is a sidebar gotcha to be aware of - see the Part 8 Field Notes page for a workaround using .gitignore.

Generating a comprehensive instructions file with a single prompt

Generating a comprehensive instructions file with a single prompt is possible once a repository has established patterns for GitHub Copilot to analyze. Rather than starting from scratch, you can use a detailed prompt that guides GitHub Copilot to read the workspace and produce a complete, structured instructions file in one pass:

Analyze this entire workspace and generate a complete .github/copilot-instructions.md file.

Your output should:
- Identify the purpose, architecture, and conventions used in this repository
- Infer coding patterns, naming conventions, folder structure, and design principles
- Detect frameworks, libraries, and tools in use
- Identify any implicit rules the codebase follows (style, patterns, do/don't rules)
- Provide guidance for how Copilot should write code, documentation, tests, and comments in this repo
- Include examples of good patterns to follow and bad patterns to avoid
- Include instructions for commit messages, PR descriptions, and documentation tone
- Use tree-style folder structures with emoji icons to describe project layout, like this:
   📂 .github/
    ├─ 📄 copilot-instructions.md
    └─ 📂 instructions/
         └─ 📄 powershell.instructions.md
   📂 .vscode/
    ├─ 📄 extensions.json
    └─ 📄 settings.json
   📂 src/
    └─ 📂 scripts/
         └─ 📄 Invoke-Example.ps1
   📄 README.md

Format the result as a polished, production-ready copilot-instructions.md file with clear sections,
headings, and examples.

The structured bullet list forces GitHub Copilot to think through each layer - architecture, conventions, patterns, examples, and rules - which produces a much more complete draft than a generic prompt.

If you also use the .github/instructions/ folder, extend the prompt to generate both at once:

Analyze this entire workspace and generate content for both:

1. .github/copilot-instructions.md
2. The .github/instructions/ folder (modular instruction files)

Your output should:
- Identify the purpose, architecture, and conventions used in this repository
- Suggest a modular breakdown for the .github/instructions/ folder
  (e.g., coding-style.instructions.md, architecture.instructions.md, testing.instructions.md, security.instructions.md)
- For each suggested file, generate a short, clear, reusable set of instructions

Format the result as a complete copilot-instructions.md file and a list of recommended files
for .github/instructions/ with their full content.

This approach works well for established repositories where patterns are already visible in the codebase. For new projects, start with the simpler prompt in step 2 above and expand the instructions as the project grows.

Maintaining the file over time

The copilot-instructions.md file is not a one-time setup - it evolves as your project grows and as you discover what guidance produces the best GitHub Copilot output.

Good maintenance habits include:

• Add conventions as you establish them - When you decide on a new pattern (like how to handle logging, error handling, or parameter validation), add it to the instructions file
• Remove rules that do not work - If a particular instruction consistently produces poor output, revise or remove it
• Keep it focused - Long, complex instruction files can confuse GitHub Copilot just as they confuse people. Aim for clear, concise rules
• Review periodically - As your project evolves, review the instructions to ensure they still reflect current practices

To update the file, you can ask GitHub Copilot for help:

Please help me review my copilot-instructions.md file. Are there any sections that
could be clearer or more specific? What common PowerShell conventions am I missing?

Real-world example

The wiki repository for this project includes a copilot-instructions.md file that defines writing style, page conventions, formatting rules, and terminology standards. Every wiki page GitHub Copilot helps create automatically follows these conventions - consistent heading levels, sentence case, proper terminology like "Visual Studio Code" instead of "VS Code", and the correct revision date format at the end of each page.

This is the practical benefit - instead of correcting GitHub Copilot's output after every interaction, you teach it your standards once and it applies them consistently.

Sharing instructions across repositories

The repo-level copilot-instructions.md file works well for project-specific conventions, but some instructions apply to everything you do - writing style, documentation standards, or coding patterns you follow across all your projects. Rather than duplicating these instructions in every repository, you can store them in a central location and reference them globally. For more information on custom instructions, see Custom instructions for GitHub Copilot in Visual Studio Code.

Storing shared instruction files

Create a folder in your OneDrive directory to hold reusable instruction files:

 📂 %USERPROFILE%\OneDrive\.github\copilot-instructions\
  ├─ 📄 base.instructions.md                       # General coding conventions
  ├─ 📄 writing-session-abstracts.instructions.md  # Session abstract writing guide
  └─ 📄 documentation-style.instructions.md        # Documentation formatting rules

Storing instruction files in OneDrive ensures they sync automatically across all your devices. Each file covers a specific topic and can be maintained independently. This gives you a single source of truth for all reusable instruction sets.

Tip

Consider turning the .github\copilot-instructions\ folder into a Git repository. This gives you full version history and branching - useful when you want to experiment with new instructions without losing what already works. Since the folder is in OneDrive, you get both cloud sync and Git history.

Referencing shared files in Visual Studio Code

Reference the shared instruction files in your global Visual Studio Code settings (settings.json) using absolute paths:

"github.copilot.chat.codeGeneration.instructions": [
  { "file": "C:\\Users\\YourName\\OneDrive\\.github\\copilot-instructions\\base.instructions.md" },
  { "file": "C:\\Users\\YourName\\OneDrive\\.github\\copilot-instructions\\documentation-style.instructions.md" }
]

These files apply to every workspace you open in Visual Studio Code unless overridden by workspace-level settings.

Important

Visual Studio Code requires absolute paths - it does not expand ~ or $HOME. Use the full path to your OneDrive directory.

Note

In a multi-root workspace, per-folder .vscode/settings.json files are not used for github.copilot.chat.codeGeneration.instructions. Use global (user-level) settings or the .code-workspace file instead. Repo-level instruction files (.github/copilot-instructions.md and .github/instructions/) are still auto-detected per workspace folder.

Combining global and repo-level instructions

When a project needs both shared and project-specific instructions, the two mechanisms work together automatically:

• Repo-level instructions - .github/copilot-instructions.md and any .instructions.md files in .github/instructions/ are auto-detected by Visual Studio Code. No settings.json configuration is required.
• External shared instructions - Files stored outside the workspace (for example, in OneDrive) must be referenced in settings.json because Visual Studio Code cannot auto-detect files outside the workspace.

To reference external files, add them to your global (user-level) settings.json or the .code-workspace file:

"github.copilot.chat.codeGeneration.instructions": [
  { "file": "C:\\Users\\YourName\\OneDrive\\.github\\copilot-instructions\\base.instructions.md" },
  { "file": "C:\\Users\\YourName\\OneDrive\\.github\\copilot-instructions\\documentation-style.instructions.md" }
]

This layered approach gives you global reusable knowledge combined with local project-specific instructions - without duplicating content across repositories. Repo-level files are picked up automatically, and external files are pulled in through settings.

Organizing multiple repo-level instruction files

As a repository grows, a single copilot-instructions.md file may not be enough. Creating a dedicated instructions/ folder inside .github/ keeps instruction files organized and easy to maintain:

 📂 your-repository/
  └─ 📂 .github/
      ├─ 📄 copilot-instructions.md          # Auto-picked up by GitHub Copilot
      └─ 📂 instructions/
           ├─ 📄 linked.instructions.md      # Companion blog post writing guide
           ├─ 📄 session.instructions.md     # Session abstract writing guide
           └─ 📄 powershell.instructions.md  # PowerShell coding standards

The copilot-instructions.md file in the .github/ root is picked up automatically by GitHub Copilot. Additional .instructions.md files inside the .github/instructions/ folder are also auto-detected - Visual Studio Code combines and adds them to the chat context without any settings.json configuration. Having them in a clearly named folder makes it obvious what they are and where they belong.

When to use each approach

Choosing the right location for your instructions depends on how broadly they apply:

Approach	Location	Applies to
Repo-level (single file)	.github/copilot-instructions.md	A single repository - auto-picked up
Repo-level (multiple files)	.github/instructions/	A single repository - auto-detected
Shared instruction files	Central folder (e.g., OneDrive) referenced via user-level settings.json or .code-workspace file	All repositories on your device - not supported in per-folder .vscode/settings.json in multi-root workspaces

Start with repo-level instructions for project-specific conventions. As you find patterns that repeat across repositories, move them to shared files and reference them globally.

Beyond instructions - newer customization primitives

The GitHub Copilot extension in Visual Studio Code supports several customization primitives beyond instruction files. These are newer capabilities that extend how GitHub Copilot can be tailored to a project:

• Prompt files (.prompt.md) - Reusable task templates that can be invoked from Copilot Chat. Useful for standardizing common tasks like generating tests, reviewing code, or drafting documentation in a consistent way
• Agent files (.agent.md) - Custom agent modes that define a specialized persona, restrict which tools the agent can use, and scope its behavior to a specific job
• Skill files (SKILL.md) - Packaged multi-step workflows that encode domain-specific knowledge and decision logic into a reusable format
• Hooks (.github/hooks/) - Policy enforcement and lifecycle automation that can block, gate, or inject context at specific points during an agent session

These primitives are available through built-in slash commands in Copilot Chat - /create-prompt, /create-agent, /create-skill, and /create-hook - which scaffold the corresponding files interactively. The /init command can bootstrap or update a workspace instructions file by analyzing the codebase.

Note

These customization primitives are evolving rapidly. The underlying file formats and extension support may change between GitHub Copilot extension updates. For the latest details, refer to the official documentation linked below.

Useful references

These resources provide further reading on the topics covered on this page:

• Custom instructions for GitHub Copilot in Visual Studio Code - Visual Studio Code documentation on custom instructions
• Customization overview for GitHub Copilot in Visual Studio Code - Visual Studio Code documentation covering prompt files, custom agents, and other customization primitives
• GitHub Copilot documentation - Official documentation for getting started with GitHub Copilot

---

Page revised: March 17, 2026