visual display of handoffs on readme

aaronpowell · aaronpowell · commit 700dfafe3f38 · 2025-11-26T11:20:16.000+11:00
diff --git a/docs/README.agents.md b/docs/README.agents.md
@@ -17,6 +17,11 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
 - Agents will have access to tools from configured MCP servers
 - Follow agent-specific instructions for optimal usage
 
+**Handoffs:**
+- Agents marked with 🔄 support handoffs to other agents (VS Code only)
+- Handoffs allow you to seamlessly transfer context between specialized agents
+- [Learn more about handoffs](https://code.visualstudio.com/docs/copilot/customization/custom-agents#_handoffs)
+
 | Title | Description | MCP Servers |
 | ----- | ----------- | ----------- |
 | [.NET Upgrade Collection](../agents/dotnet-upgrade.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-upgrade.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdotnet-upgrade.agent.md) | Perform janitorial tasks on C#/.NET code including cleanup, modernization, and tech debt remediation. |  |
@@ -44,7 +49,7 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
 | [C#/.NET Janitor](../agents/csharp-dotnet-janitor.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcsharp-dotnet-janitor.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcsharp-dotnet-janitor.agent.md) | Perform janitorial tasks on C#/.NET code including cleanup, modernization, and tech debt remediation. |  |
 | [Clojure Interactive Programming](../agents/clojure-interactive-programming.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fclojure-interactive-programming.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fclojure-interactive-programming.agent.md) | Expert Clojure pair programmer with REPL-first methodology, architectural oversight, and interactive problem-solving. Enforces quality standards, prevents workarounds, and develops solutions incrementally through live REPL evaluation before file modifications. |  |
 | [Comet Opik](../agents/comet-opik.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcomet-opik.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcomet-opik.agent.md) | Unified Comet Opik agent for instrumenting LLM apps, managing prompts/projects, auditing prompts, and investigating traces/metrics via the latest Opik MCP server. | opik<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=opik&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22opik-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=opik&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22opik-mcp%22%5D%2C%22env%22%3A%7B%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22opik-mcp%22%5D%2C%22env%22%3A%7B%7D%7D) |
-| [Context7 Expert](../agents/context7.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcontext7.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcontext7.agent.md) | Expert in latest library versions, best practices, and correct syntax using up-to-date documentation | [context7](https://github.com/mcp/upstash/context7)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D) |
+| [Context7 Expert](../agents/context7.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcontext7.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcontext7.agent.md) | Expert in latest library versions, best practices, and correct syntax using up-to-date documentation<br /><br />🔄 *Handoffs: Implement with Context7* | [context7](https://github.com/mcp/upstash/context7)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code-0098FF?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscode?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-VS_Code_Insiders-24bfa5?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-vscodeinsiders?name=context7&config=%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D)<br />[![Install MCP](https://img.shields.io/badge/Install-Visual_Studio-C16FDE?style=flat-square)](https://aka.ms/awesome-copilot/install/mcp-visualstudio/mcp-install?%7B%22url%22%3A%22https%3A%2F%2Fmcp.context7.com%2Fmcp%22%2C%22headers%22%3A%7B%22CONTEXT7_API_KEY%22%3A%22%24%7B%7B%20secrets.COPILOT_MCP_CONTEXT7%20%7D%7D%22%7D%7D) |
 | [Create PRD Chat Mode](../agents/prd.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprd.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fprd.agent.md) | Generate a comprehensive Product Requirements Document (PRD) in Markdown, detailing user stories, acceptance criteria, technical considerations, and metrics. Optionally create GitHub issues upon user confirmation. |  |
 | [Critical thinking mode instructions](../agents/critical-thinking.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcritical-thinking.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcritical-thinking.agent.md) | Challenge assumptions and encourage critical thinking to ensure the best possible solution and outcomes. |  |
 | [Debug Mode Instructions](../agents/debug.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdebug.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fdebug.agent.md) | Debug your application to find and fix a bug |  |
diff --git a/eng/constants.mjs b/eng/constants.mjs
@@ -76,7 +76,12 @@ Custom agents for GitHub Copilot, making it easy for users and organizations to
 **To Activate/Use:**
 - Access installed agents through the VS Code Chat interface, assign them in CCA, or through Copilot CLI (coming soon)
 - Agents will have access to tools from configured MCP servers
-- Follow agent-specific instructions for optimal usage`,
+- Follow agent-specific instructions for optimal usage
+
+**Handoffs:**
+- Agents marked with 🔄 support handoffs to other agents (VS Code only)
+- Handoffs allow you to seamlessly transfer context between specialized agents
+- [Learn more about handoffs](https://code.visualstudio.com/docs/copilot/customization/custom-agents#_handoffs)`,
 };
 
 const vscodeInstallImage =
diff --git a/eng/update-readme.mjs b/eng/update-readme.mjs
@@ -331,6 +331,26 @@ function generatePromptsSection(promptsDir) {
   return `${TEMPLATES.promptsSection}\n${TEMPLATES.promptsUsage}\n\n${promptsContent}`;
 }
 
+/**
+ * Get handoff information from an agent
+ * @param {string} filePath - Path to the agent file
+ * @returns {Array|null} - Array of handoff objects with label and agent, or null if no handoffs
+ */
+function getHandoffs(filePath) {
+  try {
+    const frontmatter = parseFrontmatter(filePath);
+    if (frontmatter && Array.isArray(frontmatter.handoffs) && frontmatter.handoffs.length > 0) {
+      return frontmatter.handoffs.map(h => ({
+        label: h.label || 'Unknown handoff',
+        agent: h.agent || 'unknown'
+      }));
+    }
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
 /**
  * Generate MCP server links for an agent
  * @param {string[]} servers - Array of MCP server names
@@ -472,14 +492,26 @@ function generateUnifiedModeSection(cfg) {
 
   for (const { file, filePath, title } of entries) {
     const link = encodeURI(`${linkPrefix}/${file}`);
-    const description = extractDescription(filePath);
+    let description = extractDescription(filePath);
     const badges = makeBadges(link, badgeType);
     let mcpServerCell = "";
     if (includeMcpServers) {
       const servers = extractMcpServerConfigs(filePath);
       mcpServerCell = generateMcpServerLinks(servers);
     }
 
+    // Add handoff indicator if agent supports handoffs
+    if (badgeType === "agent") {
+      const handoffs = getHandoffs(filePath);
+      if (handoffs && handoffs.length > 0) {
+        const handoffLabels = handoffs.map(h => h.label).join(', ');
+        const handoffInfo = `🔄 *Handoffs: ${handoffLabels}*`;
+        description = description && description !== "null" 
+          ? `${description}<br /><br />${handoffInfo}` 
+          : handoffInfo;
+      }
+    }
+
     if (includeMcpServers) {
       content += `| [${title}](../${link})<br />${badges} | ${
         description && description !== "null" ? description : ""
