feat: enhance agent suggestion prompt to detect and update outdated agents

- Add version comparison process to identify outdated local agents
- Introduce ⚠️ status icon for installed but outdated agents
- Add detailed comparison of remote vs local agent content
- Include update handling instructions for outdated agents
- Enhance process to fetch and compare remote versions
- Update output format to show outdated agents with specific differences

Author: yaooqinn

prompts/suggest-awesome-github-copilot-agents.prompt.md

@@ -1,6 +1,6 @@
 ---
 agent: "agent"
-description: "Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository."
+description: "Suggest relevant GitHub Copilot Custom Agents files from the awesome-copilot repository based on current repository context and chat history, avoiding duplicates with existing custom agents in this repository, and identifying outdated agents that need updates."
 tools: ["edit", "search", "runCommands", "runTasks", "changes", "testFailure", "openSimpleBrowser", "fetch", "githubRepo", "todos"]
 ---
 
@@ -13,14 +13,23 @@ Analyze current repository context and suggest relevant Custom Agents files from
 1. **Fetch Available Custom Agents**: Extract Custom Agents list and descriptions from [awesome-copilot README.agents.md](https://github.com/github/awesome-copilot/blob/main/docs/README.agents.md). Must use `fetch` tool.
 2. **Scan Local Custom Agents**: Discover existing custom agent files in `.github/agents/` folder
 3. **Extract Descriptions**: Read front matter from local custom agent files to get descriptions
-4. **Analyze Context**: Review chat history, repository files, and current project needs
-5. **Compare Existing**: Check against custom agents already available in this repository
-6. **Match Relevance**: Compare available custom agents against identified patterns and requirements
-7. **Present Options**: Display relevant custom agents with descriptions, rationale, and availability status
-8. **Validate**: Ensure suggested agents would add value not already covered by existing agents
-9. **Output**: Provide structured table with suggestions, descriptions, and links to both awesome-copilot custom agents and similar local custom agents
-   **AWAIT** user request to proceed with installation of specific custom agents. DO NOT INSTALL UNLESS DIRECTED TO DO SO.
-10. **Download Assets**: For requested agents, automatically download and install individual agents to `.github/agents/` folder. Do NOT adjust content of the files. Use `#todos` tool to track progress. Prioritize use of `#fetch` tool to download assets, but may use `curl` using `#runInTerminal` tool to ensure all content is retrieved.
+4. **Fetch Remote Versions**: For each local agent, fetch the corresponding version from awesome-copilot repository using raw GitHub URLs (e.g., `https://raw.githubusercontent.com/github/awesome-copilot/main/agents/<filename>`)
+5. **Compare Versions**: Compare local agent content with remote versions to identify:
+   - Agents that are up-to-date (exact match)
+   - Agents that are outdated (content differs)
+   - Key differences in outdated agents (tools, description, content)
+6. **Analyze Context**: Review chat history, repository files, and current project needs
+7. **Match Relevance**: Compare available custom agents against identified patterns and requirements
+8. **Present Options**: Display relevant custom agents with descriptions, rationale, and availability status including outdated agents
+9. **Validate**: Ensure suggested agents would add value not already covered by existing agents
+10. **Output**: Provide structured table with suggestions, descriptions, and links to both awesome-copilot custom agents and similar local custom agents
+    **AWAIT** user request to proceed with installation or updates of specific custom agents. DO NOT INSTALL OR UPDATE UNLESS DIRECTED TO DO SO.
+11. **Download/Update Assets**: For requested agents, automatically:
+    - Download new agents to `.github/agents/` folder
+    - Update outdated agents by replacing with latest version from awesome-copilot
+    - Do NOT adjust content of the files
+    - Use `#fetch` tool to download assets, but may use `curl` using `#runInTerminal` tool to ensure all content is retrieved
+    - Use `#todos` tool to track progress
 
 ## Context Analysis Criteria
 
@@ -46,6 +55,7 @@ Display analysis results in structured table comparing awesome-copilot custom ag
 | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ---------------------------------- | ------------------------------------------------------------- |
 | [amplitude-experiment-implementation.agent.md](https://github.com/github/awesome-copilot/blob/main/agents/amplitude-experiment-implementation.agent.md) | This custom agent uses Amplitude's MCP tools to deploy new experiments inside of Amplitude, enabling seamless variant testing capabilities and rollout of product features | ❌ No             | None                               | Would enhance experimentation capabilities within the product |
 | [launchdarkly-flag-cleanup.agent.md](https://github.com/github/awesome-copilot/blob/main/agents/launchdarkly-flag-cleanup.agent.md)                     | Feature flag cleanup agent for LaunchDarkly                                                                                                                                | ✅ Yes            | launchdarkly-flag-cleanup.agent.md | Already covered by existing LaunchDarkly custom agents        |
+| [principal-software-engineer.agent.md](https://github.com/github/awesome-copilot/blob/main/agents/principal-software-engineer.agent.md)                 | Provide principal-level software engineering guidance with focus on engineering excellence, technical leadership, and pragmatic implementation.                            | ⚠️ Outdated       | principal-software-engineer.agent.md | Tools configuration differs: remote uses `'web/fetch'` vs local `'fetch'` - Update recommended |
 
 ## Local Agent Discovery Process
 
@@ -54,19 +64,44 @@ Display analysis results in structured table comparing awesome-copilot custom ag
 3. Build comprehensive inventory of existing agents
 4. Use this inventory to avoid suggesting duplicates
 
+## Version Comparison Process
+
+1. For each local agent file, construct the raw GitHub URL to fetch the remote version:
+   - Pattern: `https://raw.githubusercontent.com/github/awesome-copilot/main/agents/<filename>`
+2. Fetch the remote version using the `fetch` tool
+3. Compare entire file content (including front matter, tools array, and body)
+4. Identify specific differences:
+   - **Front matter changes** (description, tools)
+   - **Tools array modifications** (added, removed, or renamed tools)
+   - **Content updates** (instructions, examples, guidelines)
+5. Document key differences for outdated agents
+6. Calculate similarity to determine if update is needed
+
 ## Requirements
 
 - Use `githubRepo` tool to get content from awesome-copilot repository agents folder
 - Scan local file system for existing agents in `.github/agents/` directory
 - Read YAML front matter from local agent files to extract descriptions
+- Compare local agents with remote versions to detect outdated agents
 - Compare against existing agents in this repository to avoid duplicates
 - Focus on gaps in current agent library coverage
 - Validate that suggested agents align with repository's purpose and standards
 - Provide clear rationale for each suggestion
 - Include links to both awesome-copilot agents and similar local agents
+- Clearly identify outdated agents with specific differences noted
 - Don't provide any additional information or context beyond the table and the analysis
 
 ## Icons Reference
 
-- ✅ Already installed in repo
+- ✅ Already installed and up-to-date
+- ⚠️ Installed but outdated (update available)
 - ❌ Not installed in repo
+
+## Update Handling
+
+When outdated agents are identified:
+1. Include them in the output table with ⚠️ status
+2. Document specific differences in the "Suggestion Rationale" column
+3. Provide recommendation to update with key changes noted
+4. When user requests update, replace entire local file with remote version
+5. Preserve file location in `.github/agents/` directory