Skip to content

Commit 7bd812c

Browse files
ntroghntrogh
committed
Improve intro and structure
1 parent 46b4dcc commit 7bd812c

File tree

1 file changed

+68
-82
lines changed

1 file changed

+68
-82
lines changed

‎docs/copilot/copilot-customization.md

Lines changed: 68 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,129 @@
11
---
22
ContentId: 16c73175-a606-4aab-8ae5-a507fe8947eb
33
DateApproved: 04/03/2025
4-
MetaDescription: Learn how you can customize how GitHub Copilot generates code or tests for your project by defining a set of instructions.
4+
MetaDescription: Learn how to customize GitHub Copilot Chat with custom instructions and reusable prompt files to align AI responses with your coding practices and project requirements.
55
MetaSocialImage: images/shared/github-copilot-social.png
66
---
7-
# Custom instructions for GitHub Copilot in VS Code
7+
# Customize chat with instructions and prompt files
88

9-
You can enhance Copilot's chat responses by providing it with contextual details about your team's workflow, tools, or project specifics. Instead of manually including this context in every chat query, you can create a _custom instructions_ file that automatically incorporates this information with every chat request.
9+
Customize chat responses to align with your coding practices and project requirements. This article explains two powerful customization approaches: custom instructions that apply guidelines to all your chat interactions, and prompt files that let you create, store, and share reusable AI prompts for specific tasks like generating components, reviewing code, or creating documentation.
1010

11-
Copilot applies these instructions to chat prompts in the Chat view, Quick Chat, or Inline Chat. These instructions are not displayed in the chat, but are passed to Copilot by VS Code.
11+
[*Custom instructions*](#custom-instructions) enable you to describe common guidelines or rules to get responses that match your specific coding practices and tech stack. Instead of manually including this context in every chat query, custom instructions automatically incorporate this information with every chat request. VS Code supports custom instructions for different scenarios, such as code generation, commit-message generation, code reviewing, and more.
1212

13-
You can specify custom instructions for specific purposes:
13+
[*Prompt files*](#reusable-prompt-files-experimental) allow you to craft complete prompts in Markdown files, which you can then reference in chat. Unlike custom instructions that supplement your existing prompts, prompt files are standalone prompts that you can store within your workspace and share with others. With prompt files, you can create reusable templates for common tasks, store domain expertise in your codebase, and standardize AI interactions across your team.
1414

15-
* **Code-generation instructions** - provide context specific for generating code. For example, you can specify that private variables should always be prefixed with an underscore, or that singletons should be implemented a certain way. You can specify code-generation instructions in settings, or in a Markdown file in your workspace.
15+
## Custom instructions
1616

17-
* **Test-generation instructions** - provide context specific for generating tests. For example, you can specify that all generated tests should use a specific testing framework. You can specify test-generation instructions in settings, or in a Markdown file in your workspace.
17+
VS Code supports several types of custom instructions, targeted at different scenarios: code generation, test generation, code review, commit message generation, and pull request title and description generation instructions.
1818

19-
* **Code review instructions** - provide context specific for reviewing the current editor selection. For example, you can specify that the reviewer should look for a specific type of error in the code. You can specify review-selection instructions in settings, or in a Markdown file in your workspace.
19+
You can define custom instructions in two ways:
2020

21-
* **Commit message generation instructions** - provide context specific for generating commit messages. You can specify commit-message-generation instructions in settings, or in a Markdown file in your workspace.
21+
1. Using a `.github/copilot-instructions.md` file in your workspace
22+
2. Directly in your VS Code settings through `settings.json`
2223

23-
* **Pull request title and description generation instructions** - provide context specific for generating pull request titles and descriptions. You can specify pull request title and description generation instructions in settings, or in a Markdown file in your workspace.
24-
25-
Custom instructions consist of natural language instructions and should be short, self-contained statements that add context or relevant information to supplement chat questions.
26-
27-
## Define code-generation custom instructions
28-
29-
Copilot can help you generate code, for example as part of a refactoring, generating unit tests, or implementing a feature. You might have specific libraries you want to use in your project, or a particular coding style you want to follow for the code that Copilot generates.
24+
If you define custom instructions in both the `.github/copilot-instructions.md` file and in settings, Copilot tries to combine instructions from both sources.
3025

3126
> [!NOTE]
32-
> Copilot does not apply code-generation instructions for [code completions](/docs/copilot/ai-powered-suggestions.md).
33-
34-
### Use settings
35-
36-
You can configure custom code-generation instructions by using the `setting(github.copilot.chat.codeGeneration.instructions)` setting. You can define custom instructions at the User or Workspace level.
27+
> Custom instructions for code generation are not used for [code completions](/docs/copilot/ai-powered-suggestions.md) and are only used in [chat](/docs/copilot/chat/copilot-chat.md).
3728
38-
The following code snippet shows how to define a set of instructions in the `settings.json` file. To define instruction directly in settings, configure the `text` property. To reference an external file, configure the `file` property.
39-
40-
```json
41-
"github.copilot.chat.codeGeneration.instructions": [
42-
{
43-
"text": "Always add a comment: 'Generated by Copilot'."
44-
},
45-
{
46-
"text": "In TypeScript always use underscore for private field names."
47-
},
48-
{
49-
"file": "code-style.md" // import instructions from file `code-style.md`
50-
}
51-
],
52-
```
29+
### Custom instructions example
5330

54-
An example of the contents of the `code-style.md` file:
31+
The following example demonstrates custom instructions for code generation:
5532

5633
```markdown
57-
Always use React functional components.
58-
59-
Always add comments.
34+
# Project coding standards
35+
36+
## TypeScript Guidelines
37+
- Use TypeScript for all new code
38+
- Follow functional programming principles where possible
39+
- Use interfaces for data structures and type definitions
40+
- Prefer immutable data (const, readonly)
41+
- Use optional chaining (?.) and nullish coalescing (??) operators
42+
43+
## React Guidelines
44+
- Use functional components with hooks
45+
- Follow the React hooks rules (no conditional hooks)
46+
- Use React.FC type for components with children
47+
- Keep components small and focused
48+
- Use CSS modules for component styling
49+
50+
## Naming Conventions
51+
- Use PascalCase for component names, interfaces, and type aliases
52+
- Use camelCase for variables, functions, and methods
53+
- Prefix private class members with underscore (_)
54+
- Use ALL_CAPS for constants
55+
56+
## Error Handling
57+
- Use try/catch blocks for async operations
58+
- Implement proper error boundaries in React components
59+
- Always log errors with contextual information
6060
```
6161

6262
### Use a `.github/copilot-instructions.md` file
6363

64-
You can also store custom instructions in your workspace or repository in a `.github/copilot-instructions.md` file and have VS Code automatically pick up this file.
64+
You can store custom instructions in your workspace or repository in a `.github/copilot-instructions.md` file and describe your coding practices, preferred technologies, and project requirements by using Markdown.
6565

66-
If you define custom instructions in both the `.github/copilot-instructions.md` file and in settings, Copilot tries to combine instructions from both sources.
66+
VS Code automatically includes the instructions from the `.github/copilot-instructions.md` file to every chat request and applies them for generating code.
6767

68-
> [!NOTE]
69-
> GitHub Copilot in Visual Studio also detects the `.github/copilot-instructions.md` file. If you have a workspace that you use in both VS Code and Visual Studio, you can use the same file to define custom instructions for both editors.
68+
To use a `.github/copilot-instructions.md` file:
7069

7170
1. Set the `setting(github.copilot.chat.codeGeneration.useInstructionFiles)` setting to `true` to instruct Copilot in VS Code to use the custom instructions file.
7271

7372
1. Create a `.github/copilot-instructions.md` file at the root of your workspace. If needed, create a `.github` directory first.
7473

75-
> [!TIP]
76-
> In the Explorer view in VS Code, you can create the folder and directly in one operation by typing the full path as the file name.
77-
7874
1. Add natural language instructions to the file. You can use the Markdown format.
7975

8076
Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility.
8177

82-
## Define test-generation custom instructions
78+
> [!NOTE]
79+
> GitHub Copilot in Visual Studio also detects the `.github/copilot-instructions.md` file. If you have a workspace that you use in both VS Code and Visual Studio, you can use the same file to define custom instructions for both editors.
80+
81+
### Use settings
8382

84-
You can use Copilot to generate tests for your code, for example by using the `@workspace /tests` prompt in the Chat view. You can define custom instructions to help Copilot generate tests that are specific to your project and development workflow.
83+
You can also configure custom code-generation instructions in your user or workspace settings. The following table lists the settings for each type of custom instruction.
8584

86-
To configure custom test-generation instructions, use the `setting(github.copilot.chat.testGeneration.instructions)` setting. You can define custom instructions at the User or Workspace level.
85+
| Type of instruction | Setting name |
86+
|----------------------|--------------|
87+
| Code generation | `setting(github.copilot.chat.codeGeneration.instructions)` |
88+
| Test generation | `setting(github.copilot.chat.testGeneration.instructions)` |
89+
| Code review | `setting(github.copilot.chat.reviewSelection.instructions)` |
90+
| Commit message generation | `setting(github.copilot.chat.commitMessageGeneration.instructions)` |
91+
| Pull request title and description generation | `setting(github.copilot.chat.pullRequestDescriptionGeneration.instructions)` |
92+
93+
You can define the custom instructions as text in the settings value or reference an external file in your workspace.
8794

8895
The following code snippet shows how to define a set of instructions in the `settings.json` file. To define instruction directly in settings, configure the `text` property. To reference an external file, configure the `file` property.
8996

9097
```json
91-
"github.copilot.chat.testGeneration.instructions": [
98+
"github.copilot.chat.codeGeneration.instructions": [
9299
{
93-
"text": "Always use vitest for testing React components."
100+
"text": "Always add a comment: 'Generated by Copilot'."
94101
},
95102
{
96-
"text": "Use Jest for testing JavaScript code."
103+
"text": "In TypeScript always use underscore for private field names."
104+
},
105+
{
106+
"file": "general.instructions.md" // import instructions from file `general.instructions.md`
97107
},
98108
{
99-
"file": "code-style.md" // import instructions from file `code-style.md`
109+
"file": "db.instructions.md" // import instructions from file `db.instructions.md`
100110
}
101111
],
102112
```
103113

104-
An example of the contents of the `code-style.md` file:
105-
106-
```markdown
107-
Always add code comments.
108-
109-
Always use React functional components.
110-
```
111-
112-
## Define code review custom instructions
113-
114-
You can use Copilot to review a selection of code in the editor. You can define custom instructions to help Copilot take into account specific code review criteria that are relevant to your project and development workflow.
115-
116-
To configure custom code review instructions, use the `setting(github.copilot.chat.reviewSelection.instructions)` setting. You can define custom instructions at the User or Workspace level.
117-
118-
## Define commit message generation custom instructions
119-
120-
In the Source Control view, you can use Copilot to generate a commit message for the pending code changes. You can define custom instructions to help Copilot generate a commit message that takes into account specific formatting and structure that are specific to your project and development workflow.
121-
122-
To configure custom commit message generation instructions, use the `setting(github.copilot.chat.commitMessageGeneration.instructions)` setting. You can define custom instructions at the User or Workspace level.
123-
124-
## Define pull request title and description generation custom instructions
125-
126-
When you have the [GitHub Pull Requests](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) extension installed, you can use Copilot to generate a title and description for a pull request. You can define custom instructions to help Copilot generate a title and description that take into account specific formatting and structure that are specific to your project and development workflow.
127-
128-
To configure custom pull request title and description generation instructions, use the `setting(github.copilot.chat.pullRequestDescriptionGeneration.instructions)` setting. You can define custom instructions at the User or Workspace level.
129-
130-
## Tips for defining custom instructions
114+
### Tips for defining custom instructions
131115

132116
* Keep your instructions short and self-contained. Each instruction should be a single, simple statement. If you need to provide multiple pieces of information, use multiple instructions.
133117

134118
* Don't refer to external resources in the instructions, such as specific coding standards.
135119

136120
* Make it easy to share custom instructions with your team or across projects by storing your instructions in an external file. You can also version control the file to track changes over time.
137121

122+
* Split instructions into multiple files and add multiple file references to your settings. This approach is useful for organizing instructions by topic or type of task.
123+
138124
## Reusable prompt files (experimental)
139125

140-
Prompt files (_prompts_) let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file that mimics the existing format of writing prompts in Copilot Chat (for example, `Rewrite #file:x.ts`). This allows blending natural language instructions, additional context, and even linking to other prompt files as dependencies.
126+
Prompt files (_prompts_) let you build and share reusable prompt instructions with extra context. A prompt file is a Markdown file that mimics the existing format of writing prompts in Copilot Chat (for example, `Rewrite #file:x.ts`). This allows blending natural language instructions, additional context, and even linking to other prompt files as dependencies.
141127

142128
While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction.
143129

0 commit comments

Comments
 (0)