Revise documentation for custom instructions and prompt files (#58589)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>

Author: 3 people

content/copilot/concepts/prompting/response-customization.md

@@ -200,34 +200,90 @@ For information on how to enable, create, and use prompt files, see [AUTOTITLE](
 
 {% visualstudio %}
 
-> [!NOTE] This version of this article is about custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for other environments. <!-- markdownlint-disable-line MD027 -->
+> [!NOTE] This version of this article is about custom instructions and prompt files in {% data variables.product.prodname_vs %}. Click the tabs above for other environments. <!-- markdownlint-disable-line MD027 -->
 
 ## About customizing {% data variables.product.prodname_copilot_short %} responses
 
-{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create a custom instructions file in your repository that automatically adds this information for you. The additional information is not displayed in the chat input box, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses.
+{% data variables.product.prodname_copilot %} can provide responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your prompts, you can create files in your repository that automatically add this information for you.
+
+There are two types of files you can use to provide context and instructions to {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vs %}:
+
+* **Repository custom instructions** allow you to specify instructions and preferences that {% data variables.product.prodname_copilot_short %} will consider when working in the context of the repository.
+* **Prompt files** allow you to save common prompt instructions and relevant context in Markdown files (`*.prompt.md`) that you can then reuse in your chat prompts. {% data reusables.copilot.prompt-files-available-in-editors %}
+
+While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction.
 
 {% data reusables.copilot.custom-insts-nondeterministic %}
 
 ## About repository custom instructions
 
-In {% data variables.product.prodname_vs %}, repository custom instructions consist of a single file, `.github/copilot-instructions.md`, that you create in a repository. The instructions you add to the file should be short, self-contained statements that add context or relevant information to supplement a {% data variables.product.prodname_copilot_short %} prompt.
+You can use two types of repository custom instructions in {% data variables.product.prodname_vs %}:
 
-{% data reusables.copilot.repository-custom-instructions-support %}
+* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository.
 
-### Use cases for custom instructions
+  These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository.
 
-Common use cases for repository custom instructions include:
+* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path.
 
-* **Test generation.** Create instructions for test generation, such as specifying the use of a certain test framework.
-* **Code review.** Specify instructions for reviewing code, such as telling a reviewer to look for a specific error in the code.
-* **Commit message generation.** Write instructions for generating commit messages, such as format or the type of information to include.
+  These are specified in one or more `NAME.instructions.md` files within the `.github/instructions` directory in the repository.
 
-### Example
+  By using path-specific instructions you can avoid overloading your repository-wide instructions with information that only applies to files of certain types, or in certain directories.
 
-{% data reusables.copilot.repository-custom-instructions-example %}
+See the table below for details of support for each of these types of repository custom instructions across different {% data variables.product.prodname_copilot_short %} features.
 
 For a curated collection of examples, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions).
 
+{% data reusables.copilot.repository-custom-instructions-support %}
+
+## About prompt files
+
+Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.copilot.copilot_chat_short %} (for example, `Rewrite #file:x.ts`). This allows blending natural language instructions, additional context, and even linking to other prompt files as dependencies.
+
+Common use cases include:
+
+* **Code generation**. Create reusable prompts for components, tests, or migrations (for example, React forms, or API mocks).
+* **Domain expertise**. Share specialized knowledge through prompts, such as security practices, or compliance checks.
+* **Team collaboration**. Document patterns and guidelines with references to specs and documentation.
+* **Onboarding**. Create step-by-step guides for complex processes or project-specific patterns.
+
+You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose.
+
+### Examples
+
+The following examples demonstrate how to use prompt files.
+
+* `New React form.prompt.md` - contains instructions for a reusable task to generate a form using React.
+
+  ```markdown
+  Your goal is to generate a new React form component.
+
+  Ask for the form name and fields if not provided.
+
+  Requirements for the form:
+  - Use form design system components: [design-system/Form.md](../docs/design-system/Form.md)
+  - Use `react-hook-form` for form state management:
+    - Always define TypeScript types for your form data
+    - Prefer *uncontrolled* components using register
+    - Use `defaultValues` to prevent unnecessary rerenders
+  - Use `yup` for validation:
+    - Create reusable validation schemas in separate files
+    - Use TypeScript types to ensure type safety
+    - Customize UX-friendly validation rules
+  ```
+
+* `API security review.prompt.md` - contains reusable information about security practices for REST APIs, which can be used to do security reviews of REST APIs.
+
+  ```markdown
+  Secure REST API review:
+  - Ensure all endpoints are protected by authentication and authorization
+  - Validate all user inputs and sanitize data
+  - Implement rate limiting and throttling
+  - Implement logging and monitoring for security events
+  …
+  ```
+
+For information on how to create and use prompt files, see [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=visualstudio#using-prompt-files).
+
 {% data reusables.copilot.custom-instructions-effective %}
 
 ## Next steps

content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md

@@ -39,7 +39,7 @@ This version of this article is for using repository custom instructions and pro
 
 {% visualstudio %}
 
-This version of this article is for using repository custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments.
+This version of this article is for using repository custom instructions and prompt files in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments.
 
 {% data reusables.copilot.repository-custom-instructions-about %}
 
@@ -282,7 +282,19 @@ Once saved, these instructions will apply to the current project in Eclipse that
 
 {% visualstudio %}
 
-{% data variables.product.prodname_vs %} supports a single `.github/copilot-instructions.md` custom instructions file stored in the repository.
+{% data variables.product.prodname_vs %} supports two types of custom instructions. For details of which {% data variables.product.prodname_copilot %} features support these types of instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=visualstudio#support-for-repository-custom-instructions-2).
+
+* **Repository-wide custom instructions**, which apply to all requests made in the context of a repository.
+
+  These are specified in a `copilot-instructions.md` file in the `.github` directory of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions-2).
+
+* **Path-specific custom instructions**, which apply to requests made in the context of files that match a specified path.
+
+  These are specified in one or more `NAME.instructions.md` files within the `.github/instructions` directory in the repository. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions-2).
+
+  If the path you specify matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used.
+
+## Creating repository-wide custom instructions
 
 1. In the root of your repository, create a file named `.github/copilot-instructions.md`.
 
@@ -292,6 +304,10 @@ Once saved, these instructions will apply to the current project in Eclipse that
 
    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.
 
+## Creating path-specific custom instructions
+
+{% data reusables.copilot.custom-instructions-path %}
+
 {% endvisualstudio %}
 
 {% webui %}
@@ -533,9 +549,24 @@ Custom instructions are enabled for {% data variables.copilot.copilot_code-revie
 
 {% data reusables.copilot.custom-instructions-enabling-for-ccr %}
 
+## Using prompt files
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.copilot.copilot_chat_short %} (for example, `Rewrite #file:x.ts`). You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose.
+
+### Creating prompt files
+
+1. Add a prompt file, including the `.prompt.md` file name extension inside the `.github/prompts` folder in the root of the repository. The name can contain alphanumeric characters and spaces and should describe the purpose of the prompt information the file will contain.
+1. Write the prompt instructions, using Markdown formatting.
+
+   You can reference other files in the workspace by using Markdown links—for example, `[index](../../web/index.ts)`—or by using the `#file:'../../web/index.ts'` syntax. Paths are relative to the prompt file. Referencing other files allows you to provide additional context, such as API specifications or product documentation.
+
+For more information about prompt files, see [Use prompt files in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-chat-context?view=vs-2022#use-prompt-files) in the {% data variables.product.prodname_vs %} documentation.
+
 ## Further reading
 
-* [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions)—a curated collection of examples
+* [AUTOTITLE](/copilot/tutorials/customization-library)—a curated collection of examples
 
 {% endvisualstudio %}
 

data/reusables/copilot/prompt-files-available-in-editors.md

@@ -1 +1 @@
-Prompt files are only available in {% data variables.product.prodname_vscode_shortname %} and JetBrains IDEs.
+Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}, {% data variables.product.prodname_vs %}, and JetBrains IDEs.

data/reusables/copilot/prompt-files-preview-note.md

@@ -1,3 +1,3 @@
 > [!NOTE]
-> * {% data variables.product.prodname_copilot_short %} prompt files are in {% data variables.release-phases.public_preview %} and subject to change. {% data reusables.copilot.prompt-files-available-in-editors %} See [AUTOTITLE](/copilot/concepts/prompting/response-customization?tool=vscode#about-prompt-files).
+> * {% data variables.product.prodname_copilot_short %} prompt files are in {% data variables.release-phases.public_preview %} and subject to change. {% data reusables.copilot.prompt-files-available-in-editors %} See [AUTOTITLE](/copilot/concepts/prompting/response-customization#about-prompt-files).
 > * For community-contributed examples of prompt files for specific languages and scenarios, see the [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md) repository.

data/reusables/copilot/repository-custom-instructions-support.md

@@ -6,7 +6,7 @@ The following table shows which {% data variables.product.prodname_copilot_short
 
 | | Eclipse | JetBrains IDEs | {% data variables.product.prodname_vs %} | {% data variables.product.prodname_vscode_shortname %} | {% data variables.product.prodname_dotcom_the_website %} | Xcode |
 | --- | --- | --- | --- | --- | --- | --- |
-| {% data variables.copilot.copilot_chat_short %} | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>3</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> |
+| {% data variables.copilot.copilot_chat_short %} | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>2</sup> | {% octicon "check" aria-label="Included" %} <sup>3</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> |
 | {% data variables.copilot.copilot_coding_agent %} | N/A | N/A | N/A | {% octicon "check" aria-label="Included" %} <sup>4</sup> | {% octicon "check" aria-label="Included" %} <sup>4</sup> | N/A |
 | {% data variables.copilot.copilot_code-review_short %} | N/A | {% octicon "x" aria-label="Not included" %} | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>1</sup> | {% octicon "check" aria-label="Included" %} <sup>2</sup> | {% octicon "x" aria-label="Not included" %} |