Enhance module on configuring GitHub Copilot by adding prompt files, refining agent capabilities, and improving instructional clarity across multiple documents.

Author: ChrisHowd

learn-pr/wwl-azure/configure-customize-github-copilot-visual-studio-code/7-knowledge-check.yml

@@ -78,3 +78,25 @@ quiz:
     - content: "The handoff is disabled and the agent cannot transition to the target agent."
       isCorrect: false
       explanation: "Incorrect. The `send: false` setting doesn't disable the handoff. It simply requires the developer to manually submit the pre-filled prompt rather than having it sent automatically."
+  - content: "What is the purpose of a `.prompt.md` file in the `.github/prompts/` folder?"
+    choices:
+    - content: "It defines a custom agent persona with specific tool permissions."
+      isCorrect: false
+      explanation: "Incorrect. Custom agent personas are defined in `.agent.md` files, not `.prompt.md` files."
+    - content: "It provides a reusable prompt template that can be invoked as a slash command in Copilot Chat to run a common task consistently."
+      isCorrect: true
+      explanation: "Correct. Prompt files (`.prompt.md`) are reusable prompt templates with optional YAML frontmatter and variable placeholders. Once created, they appear as slash commands in Copilot Chat, allowing the team to standardize common tasks like generating tests or producing documentation."
+    - content: "It configures which AI model Copilot uses for all chat interactions in the workspace."
+      isCorrect: false
+      explanation: "Incorrect. Prompt files define reusable prompt templates, not model configuration. Model preferences can be set per-agent or per-prompt using the `model` frontmatter field."
+  - content: "How do subagents differ from handoffs in custom agent workflows?"
+    choices:
+    - content: "Subagents and handoffs are different names for the same feature."
+      isCorrect: false
+      explanation: "Incorrect. Subagents and handoffs are distinct mechanisms. Subagents are invoked programmatically within an agent's response, while handoffs transfer control to the user to approve a transition."
+    - content: "Subagents are invoked automatically within an agent's processing and return results to the calling agent, while handoffs transfer control to the user to approve a transition to another agent."
+      isCorrect: true
+      explanation: "Correct. Subagents are called programmatically by the parent agent during its response processing—the result flows back to the calling agent automatically. Handoffs, by contrast, present a button to the user who decides whether to transition to the next agent."
+    - content: "Subagents can only run in the cloud, while handoffs run locally in VS Code."
+      isCorrect: false
+      explanation: "Incorrect. Both subagents and handoffs can run in either the client or the cloud, depending on the agent's `target` configuration."

learn-pr/wwl-azure/configure-customize-github-copilot-visual-studio-code/includes/1-introduction.md

@@ -4,14 +4,15 @@ Imagine you're a developer on a team that maintains a large C# application. Your
 
 The topics covered in this module include:
 
-- Using repository-based custom instructions to influence Copilot's coding style and guidelines.
+- Using repository-based custom instructions and prompt files to influence Copilot's coding style and guidelines.
 - Defining and using custom Copilot agents for specialized tasks such as planning, coding, and testing.
+- Configuring subagents, agent skills, and organization-level agents.
 - Chaining agents through handoffs to accomplish multi-step development scenarios.
 
 After completing this module, you'll be able to:
 
-- Customize Copilot's responses using repository-based instruction files to enforce project-specific coding styles, best practices, and guidelines.
-- Create custom GitHub Copilot agents in Visual Studio Code with tailored instructions and tool permissions.
+- Customize Copilot's responses using instruction files and prompt files to enforce project-specific coding styles, best practices, and guidelines.
+- Create custom GitHub Copilot agents in Visual Studio Code with tailored instructions, tool permissions, and subagent configurations.
 - Configure and use agent handoffs to orchestrate multi-step development workflows.
 - Implement a real-world scenario by defining custom instructions and chaining multiple custom agents to collaboratively complete a coding task.
 

learn-pr/wwl-azure/configure-customize-github-copilot-visual-studio-code/includes/2-examine-benefits-customize-github-copilot.md

@@ -4,12 +4,16 @@ GitHub Copilot provides helpful code suggestions and chat responses right away,
 
 Out-of-the-box, Copilot generates suggestions based on its general training data and the immediate code context. While this produces useful results for many common tasks, it can miss project-specific nuances. For example, your team might enforce specific architectural patterns like the repository pattern for data access, require particular naming conventions such as prefixing private fields with an underscore, or follow security practices that mandate input validation on every API endpoint. Without customization, Copilot doesn't know about these requirements and may generate code that needs significant manual editing to meet your standards.
 
-Customization addresses this challenge through two complementary approaches:
+Customization addresses this challenge through several complementary approaches:
 
 - **Custom instruction files**: Markdown files stored in your repository that provide Copilot with always-on guidelines. These files describe your coding standards, preferred libraries, naming conventions, and other project-specific rules. Copilot reads these instructions and incorporates them into every chat response, producing suggestions that are aligned with your team's expectations from the start.
 
+- **Prompt files**: Reusable prompt templates (`.prompt.md` files) that you can invoke as slash commands in Copilot Chat. While instruction files shape how Copilot responds, prompt files define what to ask—standardizing common tasks like generating tests, creating documentation, or performing code reviews so they run consistently across your team.
+
 - **Custom agents**: Specialized AI personas that you define for particular development roles. Each agent has its own set of instructions, tool permissions, and behavioral guidelines. For instance, a "Planner" agent can focus on analyzing requirements and producing implementation plans without editing code, while an "Implementer" agent can focus on writing code that follows your project's guidelines. Agents give you fine-grained control over how Copilot behaves in different stages of your workflow.
 
+- **Agent skills**: Structured descriptions of specific capabilities or expertise areas (defined in `SKILL.md` files) that agents can draw on to provide specialized knowledge. Skills complement agent instructions by exposing metadata about what an agent knows and can do.
+
 Together, these features allow you to guide Copilot toward producing output that matches your team's conventions, reducing the editing overhead and improving consistency across your codebase.
 
 ## Modern AI-assisted workflows

learn-pr/wwl-azure/configure-customize-github-copilot-visual-studio-code/includes/3-customize-copilot-responses-instruction-files.md

@@ -8,8 +8,11 @@ For example, if your `.github/copilot-instructions.md` file specifies "Use Pasca
 
 The instructions are written in natural language using Markdown formatting. Each guideline can be its own bullet point or paragraph. Whitespace between instructions is ignored when sent to the model, so you can format the file for readability without affecting how Copilot processes it.
 
+> [!TIP]
+> You can use the `/init` slash command in Copilot Chat to automatically generate a `copilot-instructions.md` file for your project. Copilot analyzes your workspace and produces a starter instruction file tailored to your project's language, framework, and structure.
+
 > [!NOTE]
-> VS Code also supports `AGENTS.md` files as always-on instructions. An `AGENTS.md` file placed in the root of your workspace works similarly to `copilot-instructions.md` and is useful when you work with multiple AI agents and want a single set of instructions recognized by all of them.
+> VS Code also supports `AGENTS.md` and `CLAUDE.md` files as always-on instructions. An `AGENTS.md` file placed in the root of your workspace works similarly to `copilot-instructions.md` and is useful when you work with multiple AI agents and want a single set of instructions recognized by all of them. `CLAUDE.md` files follow the same pattern and are recognized by Copilot in VS Code. Additionally, nested `AGENTS.md` files can be placed in subdirectories to provide context-specific instructions that apply only when Copilot operates on files within that directory or its children.
 
 ## Path-specific instructions
 
@@ -32,7 +35,13 @@ applyTo: 'src/Backend/**/*.cs'
 - Include XML documentation comments on all public methods.
 ```
 
-The `applyTo` field accepts glob patterns. Common patterns include `**/*.cs` to match all C# files, `src/Frontend/**/*.ts` to match TypeScript files in a specific directory, or `**/Tests/**/*.cs` to match test files across the project. When a file's path matches an `applyTo` pattern, Copilot automatically includes those instructions alongside the general repository instructions.
+The YAML frontmatter supports the following fields:
+
+- **applyTo**: A glob pattern that determines which files trigger the instructions. Common patterns include `**/*.cs` to match all C# files, `src/Frontend/**/*.ts` to match TypeScript files in a specific directory, or `**/Tests/**/*.cs` to match test files across the project. When a file's path matches an `applyTo` pattern, Copilot automatically includes those instructions alongside the general repository instructions.
+
+- **description**: A natural language description of what the instructions cover. Copilot uses this field for semantic matching—when you ask a question in chat, Copilot evaluates the description to determine whether the instructions are relevant to the current context, even if no file matching the `applyTo` pattern is open. For example, a description of "Guidelines for database migration scripts" helps Copilot include those instructions when you ask about database migrations.
+
+- **name**: A display name for the instruction set that appears in the Chat Instructions menu and diagnostics view.
 
 ## Organization-level instructions
 
@@ -41,7 +50,14 @@ For enterprises that maintain coding standards across multiple repositories, Git
 In Visual Studio Code, organization-level instructions are automatically detected when you're signed in to a GitHub account that has access to an organization with custom instructions configured. These instructions appear alongside your personal and workspace instructions in the Chat Instructions menu.
 
 > [!NOTE]
-> Personal instructions take the highest priority, followed by repository instructions, and then organization instructions. When multiple types of custom instructions exist, they're all provided to the AI, but higher-priority instructions take precedence when conflicts occur.
+> When multiple types of custom instructions exist, Copilot includes all of them but follows a priority order when resolving conflicts. The full instruction priority chain, from highest to lowest, is:
+> 1. Instructions entered manually in the Chat Instructions menu or pinned to the conversation.
+> 1. `.instructions.md` files (path-specific instructions).
+> 1. `.github/copilot-instructions.md` (repository-wide instructions).
+> 1. `AGENTS.md` or `CLAUDE.md` files.
+> 1. Organization-level instructions configured by a GitHub organization administrator.
+>
+> Higher-priority instructions take precedence when conflicts occur.
 
 ## How to create instruction files
 
@@ -95,6 +111,69 @@ Repository-level instructions align AI output with team conventions and reduce t
 
 Path-specific instructions allow for even more targeted guidance. Different rules can apply to frontend versus backend code, test files versus production code, or specific modules with unique requirements. This granularity ensures that suggestions are relevant to the specific area of the codebase the developer is working in.
 
+## Tips for writing effective instructions
+
+Well-crafted instructions produce significantly better results. Here are tips for getting the most out of custom instruction files:
+
+- **Explain the reasoning behind rules**. Instead of just "prefix private fields with `_`," write "Prefix private fields with `_` to distinguish them from parameters and local variables at a glance." When Copilot understands why a rule exists, it applies the rule more consistently and can extend the principle to similar situations.
+
+- **Include short code examples**. Pair guidelines with brief code snippets showing the expected pattern. For instance, follow "Use the factory pattern for complex object creation" with a two-line example. Concrete examples reduce ambiguity.
+
+- **Focus on non-obvious rules**. Don't repeat what linters and formatters already enforce. Instead, document the conventions that only your team knows—like which libraries to prefer, which patterns to follow for error handling, or which architectural boundaries exist between modules.
+
+- **Keep instructions concise and specific**. Overly long or vague instruction files dilute Copilot's attention. Each instruction should express one clear rule. Remove instructions that overlap or contradict each other.
+
+- **Separate concerns using path-specific files**. Use `.instructions.md` files with `applyTo` patterns to keep backend and frontend rules separate, test logic distinct from production code, and infrastructure scripts isolated from application code.
+
+## Prompt files
+
+In addition to instruction files that provide always-on context, Visual Studio Code supports **prompt files**—reusable prompt templates stored as `.prompt.md` files that you can invoke as slash commands in Copilot Chat.
+
+While instruction files shape how Copilot responds, prompt files define what to ask. A prompt file contains a pre-written prompt—with optional variable placeholders—that you can run on demand to execute a common task consistently. For example, you might create a prompt file that generates a code review checklist, creates a unit test for the current file, or produces API documentation in a specific format.
+
+### How prompt files work
+
+Prompt files use the `.prompt.md` extension and can be stored in the `.github/prompts/` folder of your workspace (shared with your team through version control) or in your VS Code user profile (personal, available across all workspaces). Each file contains an optional YAML frontmatter header and a Markdown body with the prompt text.
+
+The following example shows a prompt file that generates unit tests:
+
+```markdown
+---
+description: 'Generate unit tests for the current file'
+agent: 'copilot'
+tools: ['search', 'read']
+---
+# Generate Unit Tests
+
+Analyze the code in the active file and generate comprehensive unit tests.
+
+For each public method or function:
+1. Write a test for the expected behavior (happy path).
+2. Write tests for edge cases and error conditions.
+3. Use the project's existing test framework and naming conventions.
+
+Output the tests as a complete, runnable test file.
+```
+
+The YAML frontmatter for prompt files supports these fields:
+
+| Field | Description |
+|---|---|
+| `description` | A natural language description of what the prompt does. Appears in the slash command picker. |
+| `name` | An optional display name. If omitted, the filename is used. |
+| `agent` | The agent that should handle the prompt (for example, `copilot`). |
+| `model` | An optional model preference for this prompt. |
+| `tools` | Tools the prompt should have access to when executed. |
+
+### Using prompt files
+
+Once created, prompt files appear as slash commands in the Copilot Chat input. Type `/` followed by the prompt file's name (without the `.prompt.md` extension) to select and run it. For example, a file named `generate-tests.prompt.md` becomes the `/generate-tests` command.
+
+Prompt files support variable placeholders using the `${variable}` syntax. The variable `${file}` refers to the currently active file, and `${selection}` refers to the current text selection. You can also define custom variables that prompt the user for input when the prompt file is executed.
+
+> [!NOTE]
+> To enable prompt files, verify that the `chat.promptFiles` setting is turned on in VS Code. When enabled, your `.prompt.md` files are automatically detected and registered as available slash commands.
+
 ## Limitations
 
 Custom instruction files have a few important limitations to keep in mind:
@@ -107,4 +186,4 @@ Custom instruction files have a few important limitations to keep in mind:
 
 ## Summary
 
-Custom instruction files provide a structured way to guide Copilot's behavior at the repository, path, and organization levels. By creating a `.github/copilot-instructions.md` file for project-wide standards and optional `.instructions.md` files for path-specific rules, you can align AI-generated suggestions with your team's coding conventions. This reduces manual corrections, improves code consistency, and embeds your team's knowledge directly into the development workflow.
+Custom instruction files and prompt files provide a structured way to guide Copilot's behavior at the repository, path, and organization levels. By creating a `.github/copilot-instructions.md` file for project-wide standards, optional `.instructions.md` files for path-specific rules, and `.prompt.md` files for reusable prompt templates, you can align AI-generated suggestions with your team's coding conventions. Writing effective instructions—with reasoning, examples, and focused scope—maximizes the value of these customization features. Together, these tools reduce manual corrections, improve code consistency, and embed your team's knowledge directly into the development workflow.