GitHub Copilot | Custom Prompt Files & Folder Structure for Teams

After nearly two years with GitHub Copilot, I’ve seen the skills needed to master it grow more complex, especially with the launch of agent mode. The push to create custom prompts has grown, and this is even more pronounced with the release of Model-Context-Protocol (MCP) servers.

In this post, I will share my point of view on how to use GitHub Copilot custom prompts effectively, and how they can be shared within a team or organization. My motivation is to give readers like you an idea on how this can be done. Here are some use cases:

1. Coding Standards: Ensuring that GitHub Copilot’s suggested code adheres to the development team’s coding standards.
2. Code Reviews: Reusing the same coding standards prompt for code reviews.
3. Test-Driven Development (TDD): Generating tests from existing code and creating tests that will fail first, before writing the corresponding code.
4. External URL References: Creating prompts that extract information from external URLs that the team finds useful.
5. And more…

By incorporating these custom prompts, teams can ensure consistency, improve code quality, and streamline their development processes.

Disclaimer: The tips I share in this post are my personal opinions. If you would like to learn on your own from the official sources, here are the links:

1. VSCode: Tips and Tricks for Copilot
2. VSCode: Custom instructions for GitHub Copilot
3. VSCode: Better AI results with custom instructions
4. GitHub: How to get LLMs to do what you want
5. GitHub: When to use AI Agent Mode

While most of the features only work on VSCode at the moment, it is still good to start organizing files in this way in preparation for the time when other IDEs support these features.

Proposed Folder Structure

GIT-REPO-FOLDER/
├── .github/
│   ├── prompt-snippets/
│   │   ├── coding-standards.md
│   │   ├── commit-message.md
│   │   ├── copilot-personality.md
│   ├── prompts/
│   │   ├── agent.data-engineer.prompt.md
│   │   ├── agent.software-engineer.prompt.md
│   │   ├── fetch.devkit.prompt.md
│   │   ├── task-manager.prompt.md
│   │   ├── unit-tester.prompt.md
│   ├── ...
│   └── copilot-instructions.md
├── src/
├── ...
└── README.md

Proposed Folder Structure

This is my proposed folder structure. Here’s the description for each item:

• .github/: This is the default folder where GitHub recommends all custom prompts be saved.
• .github/prompts/: This is the default folder for reusable prompt files. While this folder can be changed through the IDE settings, it is best to use the default location so that the prompt files are ready to use for all developers who have cloned this repo.
• .github/prompt-snippets/: This is a folder NOT specified by GitHub. This is an extra folder that contains reusable prompt snippets that are referred to by copilot-instructions.md and the other *.prompt.md files.

This folder structure is implemented in this repository. (Note that this repo also contains my prompt experiments.)

If you are using a different Git repository other than GitHub, that’s okay! You can still create the .github/ folder for your custom prompts, and your IDE will still recognize it.

Custom Prompt Features

This section contains the TL;DR of the GitHub Copilot features I used and why I structured the folders as such.

Copilot Instructions File (.github/copilot-instructions.md)

The custom instructions feature is the first custom prompt file feature released by GitHub in 2024. The contents of this copilot-instructions.md file are always added to every Copilot Chat context, including inline chat and IDE context menu options such as Right-Click > Copilot > Review and Comment.

One neat trick I learned from this article is to add references to other *.md files in the prompt file. GitHub Copilot can retrieve the contents of these files as long as they are in the same workspace folder that’s open in your IDE. And since GitHub Copilot supports images, the copilot-instructions.md file can include references to designs, diagrams and screenshots.

[Coding Standards](./prompt-snippets/coding-standards.md)

[Response Personality](./prompt-snippets/copilot-personality.md)

## Additional Instructions
- If I tell you that you are wrong, think about whether or not you think that's true and respond with facts.
- Avoid apologizing or making conciliatory statements.
- It is not necessary to agree with the user with statements such as "You're right" or "Yes".
- Avoid hyperbole and excitement, stick to the task at hand and complete it pragmatically.
- Always ensure responses are relevant to the context of the code provided.
- Avoid unnecessary detail and keep responses concise.
- Revalidate before responding. Think step by step.

copilot-instructions.md

Generate SQL statements for Postgres database.
The schema of this database is found in this [diagram](/data-engineer/sample-db-schema.png) file.
For additional reference, the database schema is also scripted in this [SQL file](/data-engineer/sample-db-create.sql).

Before generating SQL statements:
- Understand the relationship between the tables in the database.
- Determine the filtering criteria and conditions for data retrieval.
- Validate the expected outcome of the query.
- Think step-by-step and revalidate before responding.

Data Engineer custom prompt file

Custom prompts only influence Copilot Chat features. At this time, there is no way to create custom prompts for Copilot Code Completions.

As multiple custom prompts are being stitched together, it is very important to ensure that your prompts do not conflict with each other. For example, if your copilot-instructions.md says “use camel casing,” do not have a prompt-snippet that says “use snake_case.”

Prompt Files (.github/prompts/*.prompt.md)

These are reusable custom prompt files that developers must explicitly add to the context before they are used. They are useful for having ready-made prompts for very specific tasks.

Custom Prompts for Specific Tasks

For example, developers who practice Test-Driven Development (TDD) will build unit tests first before writing code. In doing so, they might follow the Arrange-Act-Assert (AAA) pattern in writing these tests. Without a reusable prompt file, a developer would always need to instruct GitHub Copilot to write tests following AAA (and it doesn’t always get it right). However, if developers can easily add a prompt file like unit-tester.prompt.md, this task becomes much easier.

# Unit Test Generation Guidelines

You are a unit test generator assistant.
Strictly follow these rules when generating tests:

## Test Structure
Use the AAA (Arrange-Act-Assert) pattern for structuring tests:
  1. **Arrange**: Set up test data and preconditions
  2. **Act**: Execute the code being tested
  3. **Assert**: Verify the results

Java example:
```java
@Test
public void shouldReturnTrue_WhenInputIsValid() {
    // Arrange
    MyClass myClass = new MyClass();
    String input = "validInput";

    // Act
    boolean result = myClass.isValid(input);

    // Assert
    assertTrue(result);
}
```

## Naming Convention
- Name tests as `should_ExpectedBehavior_When_StateUnderTest`
- Use *clear*, descriptive names that document the test's purpose

... more instructions ...

unit-tester.prompt.md

It doesn’t work on your IDE? Currently, most of these features only work on VSCode, development work for other IDEs are in progress. If this is the case for your IDE, the workaround is to manually add the prompt file to your chat context. This is usually done by dragging and dropping the prompt .md file or by clicking the [+] button in your IDE’s Copilot Chat.

Custom Prompts for Agent Mode

Some prompt files are specifically written for agent mode. I named these files in the format agent.<use-case>.prompt.md to quickly distinguish them from other prompt files.

Custom Prompts with External URLs

Starting from VSCode v1.99, GitHub Copilot can retrieve content from an internet or intranet URL and add it to the Copilot Chat context. But, probably because it’s still in preview, it does not always fetch the content automatically. So for now, I named the prompts that contain external references in this format fetch.<use-case>.prompt.md. This gives me the visual queue to explicitely add the fetch tool in the chat.

IDE Settings

Some prompt files are set in the IDE settings. For example, GitHub Copilot in VSCode has a setting for specifying the custom prompt for commit messages and pull request descriptions:

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "file": "./.github/prompt-snippets/commit-message.md" }
  ],  
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    { "file": "./.github/prompt-snippets/commit-message.md" }
  ]
}

For this, I used the same custom prompt file for both settings.

Start with a summary of the changes, with Gen-alpha or Gen-Z slangs and emoticons. Then follow with a list of bullet points detailing the files changed, what was changed, and the reason for the change.

commit-message.md

Custom Prompt Distribution

Now that we have all these custom prompt files, how do we share them with developers working on different projects across various Git repositories? Here are two possible approaches:

Approach 1: Publish Pattern - Push to Multiple Repositories

One idea is to create a shared repository that pushes updates to a list of Git repos whenever a prompt file is changed.

• Pro: This approach encourages developers to collaborate and modify prompt files in this shared repo, fostering inner-sourcing practices.
• Con: Maintenance of destination repositories is centrally managed.

graph LR
    A[Source Repo] -->|Get .md files| B[.github/*.md]
    B --> C{Sync to Target Repos}
    C -->|Copy| D[Target Repo 1]
    C -->|Copy| E[Target Repo 2]
    C -->|Copy| F[Target Repo n]

Check out my GitHub Actions workflow that does exactly this.

Approach 2: Pull Pattern - Pull from a Shared Repository

Another idea is to do the reverse, where the project repository pulls the changes rather than the shared repository pushing updates.

• Pro: Lets developer teams decide if they want to use the shared custom prompts.
• Con: Harder to enforce prompt standards (e.g. coding guidelines specified in copilot-instructions.md).

Check out my GitHub Actions workflow that follows this approach.

Conclusion: Be Agile in this Rapidly Innovating Space

In this post, I shared how I would organize GitHub Copilot custom prompt files with the features available today. This space is rapidly evolving, with new capabilities being released frequently. For example, GitHub recently announced a new feature for organization custom instructions which applies to GitHub.com Copilot chat. This suggests that organization settings for custom prompts affecting the IDE may be coming soon.

So my advice is to be agile. Watch this space and adapt. This is a wonderful time for developers to experiment with prompts and share best practices with each other.