Add Copilot customization article

docs/copilot/copilot-customization.md

@@ -0,0 +1,123 @@
+---
+Order: 11
+Area: copilot
+TOCTitle: Customizing Copilot
+ContentId: 16c73175-a606-4aab-8ae5-a507fe8947eb
+PageTitle: Customize GitHub Copilot in VS Code
+DateApproved: 10/03/2024
+MetaDescription: Learn how you can customize how GitHub Copilot generates code or tests for your project by defining a set of instructions.
+MetaSocialImage: images/shared/github-copilot-social.png
+---
+# Custom instructions for GitHub Copilot in VS Code
+
+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.
+
+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.
+
+You can specify custom instructions for specific purposes:
+
+* **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.
+
+* **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.
+
+Custom instructions consist of natural language instructions and should be short, self-contained statements that add context or relevant information to supplement chat questions.
+
+## Define code-generation custom instructions
+
+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.
+
+### Use settings
+
+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, and you can also specify language-specific instructions. Get more information about [language-specific settings](/docs/getstarted/settings.md#language-specific-editor-settings).
+
+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.
+
+```json
+  "github.copilot.chat.codeGeneration.instructions": [
+    {
+      "text": "Always add a comment: 'Generated by Copilot'."
+    },
+    {
+      "text": "In TypeScript always use underscore for private field names."
+    },
+    {
+      "file": "code-style.md" // import instructions from file `code-style.md`
+    }
+  ],
+```
+
+An example of the contents of the `code-style.md` file:
+
+```markdown
+Always use React functional components.
+
+Always add comments.
+```
+
+### Use a `.github/copilot-instructions.md` file
+
+You can also store custom instructions in your workspace or repository in a `.github/copilot-instructions.md` file and have VS Code automatically picks up this file.
+
+> [!NOTE]
+> GitHub Copilot in Visual Studio also detect 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.
+
+1. Set the `setting(github.copilot.chat.codeGeneration.useInstructionFiles)` setting to `true` to instruct Copilot in VS Code to use the custom instructions file.
+
+1. Create a `.github/copilot-instructions.md` file at the root of your workspace. If needed, create a `.github` directory first.
+
+    > [!TIP]
+    > 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.
+
+1. Add natural language instructions to the file. You can use the Markdown format.
+
+    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.
+
+## Define test-generation custom instructions
+
+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.
+
+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, and you can also specify language-specific instructions. Get more information about [language-specific settings](/docs/getstarted/settings.md#language-specific-editor-settings). For example, you might specify a different testing framework to use for each language.
+
+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.
+
+```json
+  "github.copilot.chat.testGeneration.instructions": [
+    {
+      "text": "Always use vitest for testing React components."
+    },
+    {
+      "text": "Use Jest for testing JavaScript code."
+    },
+    {
+      "file": "code-style.md" // import instructions from file `code-style.md`
+    }
+  ],
+```
+
+An example of the contents of the `code-style.md` file:
+
+```markdown
+Always add code comments.
+
+Always use React functional components.
+```
+
+## Tips for defining custom instructions
+
+* 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.
+
+* Don't refer to external resources in the instructions, such as specific coding standards,
+
+* Define language-specific instructions to get more accurate generated code for each language.
+
+* 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.
+
+## Settings
+
+* `setting(github.copilot.chat.codeGeneration.instructions)` <i class="codicon codicon-beaker"></i>: A set of instructions that are added to Copilot requests that generate code.
+* `setting(github.copilot.chat.codeGeneration.useInstructionFiles)` <i class="codicon codicon-beaker"></i>: Controls whether code instructions from `.github/copilot-instructions.md` are added to Copilot requests.
+* `setting(github.copilot.chat.testGeneration.instructions)` <i class="codicon codicon-beaker"></i>: A set of instructions that are added to Copilot requests that generate tests.
+
+## Related content
+
+* Learn how you can use AI chat conversations with [Copilot Chat](/docs/copilot/copilot-chat.md).

docs/copilot/copilot-extensibility-overview.md

@@ -1,5 +1,5 @@
 ---
-Order: 10
+Order: 13
 Area: copilot
 TOCTitle: Copilot Extensibility
 ContentId: e375ec2a-43d3-4670-96e5-fd25a6aed272

docs/copilot/copilot-settings.md

@@ -1,5 +1,5 @@
 ---
-Order: 11
+Order: 14
 Area: copilot
 TOCTitle: Settings Reference
 ContentId: 7b232695-cbbe-4f3f-a625-abc7a5e6496c
@@ -51,10 +51,7 @@ The team is continuously working on improving Copilot in VS Code and adding new
 
 ## Customize Copilot prompts
 
-* `setting(github.copilot.chat.codeGeneration.instructions)` <i class="codicon codicon-beaker"></i>: A set of instructions that will be added to Copilot requests that generate code.
+c
-* `setting(github.copilot.chat.codeGeneration.useInstructionFiles)` <i class="codicon codicon-beaker"></i>: Controls whether code instructions from `.github/copilot-instructions.md` are added to Copilot requests.
-* `setting(github.copilot.chat.testGeneration.instructions)` <i class="codicon codicon-beaker"></i>: A set of instructions that will be added to Copilot requests that generate tests.
-
 ## Debugging settings
 
 * `setting(github.copilot.chat.startDebugging.enabled)` _(Preview)_: Enables the experimental `/startDebugging` intent in the Chat view to generate debugging configuration.