Capgemini · ksulikow · May 26, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 3, 2026
diff --git a/.github/README.github.md b/.github/README.github.md
@@ -3,7 +3,7 @@
 This directory contains repository-level configuration and assets that tailor GitHub and GitHub Copilot to this project. It centralizes:
 - Copilot repository instructions and guidance
 - Custom Agents used in Copilot Chat (new format)
-- Custom Chat Modes used in Copilot Chat (deprecated, for backward compatibility)
+- Reusable Skills for domain-specific guidance
 - Reusable Prompt files (slash commands)
 - Instruction files for languages/domains
 - GitHub Actions workflows (CI/CD) scaffolding
@@ -14,7 +14,7 @@ Scope: This README documents the `.github/` directory only. For project-wide ove
 
 ### Copying Copilot Customisations
 
-The custom agents, chat modes, instructions, and prompts are designed to be portable across repositories with the same directory layout. For general guidance and caveats, see the root [README: “Copying Copilot Customisations”](../README.md#7-copying-copilot-customisations).
+The custom agents, instructions, and prompts are designed to be portable across repositories with the same directory layout. For general guidance and caveats, see the root [README: “Copying Copilot Customisations”](../README.md#7-copying-copilot-customisations).
 
 Most files contain **HTML comments** inlined with additional context (functionality, intent, and prompting techniques). View the raw source to see these notes.
 
@@ -35,24 +35,28 @@ See also:
 
 - [Custom Agents](./agents/README.md)
 
-> **Note:** As of October 2025, GitHub renamed "Chat Modes" to "Agents". See [GitHub's announcement](https://github.blog/changelog/2025-10-28-custom-agents-for-github-copilot/) for details.
-
 Agents provide specialized behaviors in Copilot Chat (e.g., Developer, Code Review, Testing). Each agent documents its persona, process, constraints, and available tools. Files live under `./agents/` and use the `.agent.md` extension.
 
 Available agents:
 - **Developer** - Test-driven development with quality gates and design-first methodology
 - **Code Reviewer** - Systematic code review with best practices enforcement
+- **Documentation** - Documentation authoring and maintenance aligned to docs SSOT
 - **Tester** - BDD-focused testing approach with comprehensive test coverage
 
-> **Note:** VS Code now ships with built-in Planner and Documentation agents. This repository provides complementary agents that don't duplicate those built-in capabilities.
+> **Note:** VS Code now ships with a built-in Planner/Plan agent. This repository provides a custom Documentation agent because built-in Documentation is no longer available.
 
-### Custom Chat Modes (Deprecated)
+<a name="copilot-migration-status"></a>
+### Copilot Migration Status
 
-- [Custom Chat Modes](./chatmodes/README.md) *(deprecated)*
+This repository is agent-first for current GitHub Copilot and VS Code releases.
 
-> ⚠️ **DEPRECATED**: The `.github/chatmodes/` directory is maintained for backward compatibility with VS Code. New development should use the `.github/agents/` directory with the `.agent.md` extension.
+- `agents/Developer.agent.md` is the current development workflow artifact
+- `agents/CodeReviewer.agent.md` is the current review workflow artifact
+- `agents/Tester.agent.md` is the current testing workflow artifact
+- `agents/Documentation.agent.md` is the current documentation workflow artifact
+- Planner behavior relies on the built-in VS Code Planner/Plan agent
 
-Chat Modes provide specialized behaviors in Copilot Chat (e.g., Developer, Code Review, Documentation, Testing, Planner). Each mode documents its persona, process, constraints, and available tools. Files live under `./chatmodes/` and use the `.chatmode.md` extension.
+The repository no longer keeps retired legacy chat-format files. If you are migrating an older setup, move those files to `.github/agents/`, rename them to `.agent.md`, and update any repo documentation or prompt references to use the current agent format.
 
 ### Custom Instructions
 
@@ -64,6 +68,15 @@ Instruction files are small, focused rule sets with optional frontmatter (e.g.,
 - `docs.instructions.md` (applies to all `**/*.md`)
 - `bdd-tests.instructions.md` (applies to `**.feature`)
 
+### Custom Skills
+
+- [Custom Skills](./skills/README.md)
+
+Skills are reusable, domain-focused guidance documents that help assistants choose the right workflow and produce consistent outputs for specific tasks.
+
+Current example:
+- `docs-ssot-helper` - demonstrates how to update documentation while preserving SSOT alignment, canonical locations, and cross-links.
+
 ### Custom Prompts
 
 - [Custom Prompts](./prompts/README.md)
@@ -72,7 +85,7 @@ Reusable prompts act like slash commands in Copilot Chat (e.g., `/write-adr`, `/
 
 ## GitHub Actions Customisation
 
-The `./workflows/` folder holds GitHub Actions. It’s currently empty and ready for CI/CD jobs (for example: lint Markdown, validate instruction frontmatter, run tests). Add workflow files as needed following standard GitHub Actions practices. Prefer referencing SSOT anchors (e.g., Quality Policy) in validation jobs.
+The `./workflows/` folder holds GitHub Actions such as `policy-lint.yml` and `docs-lint.yml`. Add workflow files as needed following standard GitHub Actions practices. Prefer referencing SSOT anchors (e.g., Quality Policy) in validation jobs.
 
 References:
 - GitHub Actions docs: https://docs.github.com/actions

diff --git a/.github/agents/CodeReviewer.agent.md b/.github/agents/CodeReviewer.agent.md
@@ -1,12 +1,12 @@
 ---
 description: 'Code Reviewer Agent'
-tools: ['search/codebase', 'search', 'usages', 'problems', 'changes']
+tools: ['search', 'read']
 ---
 
 <!-- This is an example Agent, rather than a canonical one -->
 # Code Reviewer Agent Instructions
 
-You are in Code Reviewer Mode. Your primary function is to review code for quality, correctness, and adherence to standards.
+You are a Code Reviewer Agent. Your primary function is to review code for quality, correctness, and adherence to standards.
 
 <!-- SSOT reference: avoid duplication; link to central policies -->
 Note: Use `.github/copilot-instructions.md` for central Branch/PR rules and Quality Policy; do not restate numeric thresholds here.

diff --git a/.github/agents/Developer.agent.md b/.github/agents/Developer.agent.md
@@ -1,6 +1,6 @@
 ---
 description: 'Developer Agent'
-tools: ['search/codebase', 'usages', 'problems', 'changes', 'testFailure', 'runCommands/terminalSelection', 'runCommands/terminalLastCommand', 'openSimpleBrowser', 'fetch', 'findTestFiles', 'search/searchResults', 'githubRepo', 'todos', 'edit/editFiles', 'runNotebooks', 'new', 'runCommands', 'runTasks']
+tools: ['search/codebase', 'search/usages', 'read/problems','execute/testFailure', 'read/terminalSelection', 'read/terminalLastCommand', 'web/fetch', 'web/githubRepo', 'todo', 'edit/editFiles', 'execute/runNotebookCell', 'read/getNotebookSummary', 'read/readNotebookCellOutput', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/createAndRunTask','execute/runTask','read/getTaskOutput']
 ---
 
 <!-- This is an example Agent, rather than a canonical one -->
@@ -11,7 +11,7 @@ PROMPTING TECHNIQUES: Persona priming, role clarity, and explicit mandate to bui
 -->
 # Developer Instructions
 
-You are in Developer Mode. Your purpose is to assist in writing, reviewing, and improving code.
+You are a Developer Agent. Your purpose is to assist in writing, reviewing, and improving code.
 
 <!-- SSOT reference: avoid duplication; link to central policies -->
 Note: Follow central policies in `.github/copilot-instructions.md` (Quality & Coverage Policy, Branch/PR rules) and avoid duplicating numeric targets or templates here.

diff --git a/.github/chatmodes/Documentation.chatmode.md → .github/agents/Documentation.agent.md b/.github/chatmodes/Documentation.chatmode.md → .github/agents/Documentation.agent.md
@@ -1,18 +1,18 @@
 ---
-description: 'Documentation Mode'
-tools: ['search/codebase', 'search', 'edit/editFiles', 'usages', 'problems', 'changes', 'fetch']
+description: 'Documentation Agent'
+tools: ['search/codebase', 'search', 'edit/editFiles', 'search/usages', 'read/problems', 'web/fetch']
 ---
 
-<!-- This is an example Chat Mode, rather than a canonical one -->
-# Documentation Mode Instructions
+<!-- This is an example Agent, rather than a canonical one -->
+# Documentation Agent Instructions
 
-You are in Documentation Mode. Your purpose is to assist in writing and improving documentation.
+You are a Documentation Agent. Your purpose is to assist in writing and improving documentation.
 
 <!-- SSOT reference: avoid duplication; link to central policies -->
 Note: Use `.github/instructions/docs.instructions.md` as the SSOT for workflow, templates, formatting, and saving rules; do not duplicate them here.
 
 <!--
-Purpose: Define Documentation Mode behavior and constraints. Treat sections as rules for planning, drafting, reviewing, and publishing docs.
+Purpose: Define Documentation Agent behavior and constraints. Treat sections as rules for planning, drafting, reviewing, and publishing docs.
 How to interpret: Focus on documentation artifacts; do not alter product code unless explicitly requested to add comments or examples. Prefer clarity and structure.
 -->
 
@@ -83,8 +83,8 @@ Use saving and location guidance in `.github/instructions/docs.instructions.md`.
 
 ## Documentation Process (Flow)
 <!--
-This chat mode does not restate the flow. Use the canonical source of truth (SSOT).
+This agent does not restate the flow. Use the canonical source of truth (SSOT).
 -->
 - Reference: See `.github/instructions/docs.instructions.md#documentation-process-flow` for the canonical mermaid flow.
 
-<!-- © Capgemini 2025 -->
+<!-- © Capgemini 2025 -->
diff --git a/.github/agents/README.md b/.github/agents/README.md
@@ -2,17 +2,18 @@
 
 This document explains how we author and maintain custom agents for Copilot in this repository. It is written for contributors who will create, review, or update agent definition documents. The goal is to describe what a custom agent is, how it is structured, and best practices for crafting clear, safe, and testable instructions.
 
-> **Note:** As of October 2025, GitHub renamed "Chat Modes" to "Agents". See [GitHub's announcement](https://github.blog/changelog/2025-10-28-custom-agents-for-github-copilot/) for details. VS Code now includes built-in Planner and Documentation agents, so this repository provides agents that complement (not duplicate) those built-in capabilities.
+> **Note:** VS Code now includes a built-in Planner/Plan agent.
 
 A custom agent is a bundled set of instructions, constraints, and examples that guide the language model to behave in a consistent, predictable way for a particular task or personality. Agents encode the expected role (persona), the step-by-step process the assistant should follow, the allowed output formats, and representative examples that demonstrate correct and incorrect behavior. By keeping these definitions explicit and version-controlled, teams can iterate on assistant behavior and reuse agents across projects.
 
 ## Agents in this repository
 
 - [Code Reviewer](CodeReviewer.agent.md)
 - [Developer](Developer.agent.md)
+- [Documentation](Documentation.agent.md)
 - [Tester](Tester.agent.md)
 
-> **Note:** Documentation and Planner agents are now built-in to VS Code and are not duplicated here. For legacy compatibility, see [`.github/chatmodes/`](../chatmodes/README.md) (deprecated).
+> **Note:** Planner/Plan is built-in to VS Code and is not duplicated here.
 
 ### SSOT and anti-duplication
 
@@ -25,7 +26,7 @@ Agents may include small, agent-specific process steps or examples, but must not
 
 ## Official Docs
 
- - [Visual Studio Code custom agents docs](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes)
+ - [Visual Studio Code custom agents docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
  - [GitHub custom agents announcement](https://github.blog/changelog/2025-10-28-custom-agents-for-github-copilot/)
 
 ## Structure of a Custom Agent Definition
@@ -36,22 +37,37 @@ An agent definition document is a small, opinionated specification that the runt
 
 Agent files are Markdown documents that use the `.agent.md` extension. For workspace-shared agents, place files in the `.github/agents/` folder so collaborators can discover and use them; for personal agents put them in your VS Code profile folder. Name the file to match the agent's `name` frontmatter (kebab-case) for clarity, e.g. `code-synthesis.agent.md`.
 
-You can create a new agent using the VS Code command palette (Chat: New Mode File) or via Configure Chat > Modes in the Chat view; the editor will scaffold an `.agent.md` file for you.
+You can create a new agent using the VS Code command palette (`Chat: New Custom Agent`) or via Configure Chat > Agents in the Chat view; the editor will scaffold an `.agent.md` file for you.
 
 ### Frontmatter (VS Code keys)
 
-VS Code recognizes a small set of frontmatter keys that affect how agents behave in the editor and which tools are available. At minimum include these keys in the top YAML frontmatter so VS Code can display and configure the agent correctly:
+VS Code recognizes a broader set of frontmatter keys that affect how agents behave in the editor and which tools are available. Common keys include:
 
 - `description` (string): Brief description used as placeholder text in the chat input and as hover text in the agent picker.
+- `name` (string, optional): Display name shown in the agents picker. If omitted, VS Code uses the file name.
+- `argument-hint` (string, optional): Hint text that guides users on how to invoke the agent.
 - `tools` (list[string]): Names of tools or tool sets available for this agent (for example: `['codebase','fetch','search']`). Use the Configure Tools action to select valid tool names.
+- `agents` (list[string], optional): Allowable subagents when the agent tool is enabled.
+- `handoffs` (list, optional): Suggested next-agent transitions shown after a response.
+- `user-invocable` (boolean, optional): Controls whether the agent appears in the agents picker.
+- `disable-model-invocation` (boolean, optional): Prevents the agent from being invoked as a subagent.
+- `target` (string, optional): Target environment such as `vscode` or `github-copilot`.
 - `model` (string, optional): Model override for this agent. If omitted, the user's selected model is used.
 
+`infer` is deprecated in current VS Code releases. Prefer `user-invocable` and `disable-model-invocation` for visibility and subagent control.
+
 Example frontmatter (VS Code-focused):
 
 ```yaml
 ---
+name: developer
 description: Generate an implementation plan for a feature or refactor.
 tools: ['codebase', 'search', 'fetch']
+handoffs:
+	- label: Start Review
+		agent: codereviewer
+		prompt: Review the proposed implementation for correctness and maintainability.
+		send: false
 model: Claude Sonnet 4
 ---
 ```
@@ -155,15 +171,15 @@ Practical guidance:
 Example (illustrative) definition fragment:
 
 ```xml
-<MODE name="code-synthesis">
+<AGENT_PROFILE name="code-synthesis">
 	<PERSONA tone="concise">You are a senior backend engineer. Do not invent facts.</PERSONA>
 	<SAFETY>Refuse illegal requests. Do not reveal secrets.</SAFETY>
 	<PROCESS>
 		<STEP>Ask clarifying questions when needed</STEP>
 		<STEP>Propose a short plan</STEP>
 		<STEP>Produce implementation and tests</STEP>
 	</PROCESS>
-</MODE>
+</AGENT_PROFILE>
 ```
 
 Because these tags are embedded in the definition itself they can be parsed by tools that validate agents, and they act as strong reinforcement anchors within the instruction text.

diff --git a/.github/agents/Tester.agent.md b/.github/agents/Tester.agent.md
@@ -1,6 +1,6 @@
 ---
 description: 'Tester Agent'
-tools: ['codebase', 'search', 'editFiles', 'usages', 'problems', 'changes', 'terminalSelection', 'terminalLastCommand', 'runCommands']
+tools: ['search/codebase', 'search', 'edit/editFiles', 'search/usages', 'read/problems', 'read/terminalSelection', 'read/terminalLastCommand', 'execute/getTerminalOutput','execute/runInTerminal','read/terminalLastCommand','read/terminalSelection']
 ---
 
 # Tester Agent Instructions
@@ -10,14 +10,14 @@ Purpose: Define the Testing Agent behavior and constraints. Treat sections below
 How to interpret: Prioritize test authoring and test quality. Do not implement production code unless the user expressly asks; focus on tests that drive design and verify behavior.
 -->
 
-You are in Testing Mode. Your role is to help write, refactor, and suggest tests.
+You are a Testing Agent. Your role is to help write, refactor, and suggest tests.
 
 <!-- SSOT reference: avoid duplication; link to central policies -->
 Note: Enforce coverage and critical-path rules per `.github/copilot-instructions.md#quality-policy`. For BDD, follow `.github/instructions/bdd-tests.instructions.md`.
 
 ## Core Responsibilities
 <!--
-Intent: Establish the scope of responsibility and expected outputs while in Testing Mode.
+Intent: Establish the scope of responsibility and expected outputs while acting as the Testing Agent.
 How to interpret: Produce test plans and test code, suggest refactors to tests, and identify missing cases. Keep feedback specific and actionable.
 -->
 - **Write Unit Tests**: Generate unit tests for individual functions and components.
@@ -43,7 +43,7 @@ How to interpret: Apply these steps for each new or updated test. Prefer fast, r
 
 ## Choosing the Right Test Type (Decision Guide)
 <!--
-Intent: Decision policy for selecting unit vs integration vs E2E coverage.
+Intent: Decision policy for selecting unit, integration, or E2E coverage.
 How to interpret: Default to the lowest level that provides confidence; add higher-level tests for cross-boundary behavior and critical user journeys.
 -->