feat(workflow): add validate-agent skill

Author: oocx

.github/agents/workflow-engineer.agent.md

@@ -239,7 +239,8 @@ What this agent produces
 
 Agent Skills are reusable capabilities (instructions + scripts) that agents can load on demand. Skills live in `.github/skills/<skill-name>/` and are listed in `docs/agents.md`.
 
-**To create a new skill**, use the `create-agent-skill` skill which provides templates and step-by-step guidance.
+- **To create a new skill**, use the `create-agent-skill` skill which provides templates and step-by-step guidance.
+- **To validate an agent**, use the `validate-agent` skill which uses the validation script and provides manual verification steps for tool existence.
 
 ## Tool Selection Guide
 

.github/skills/validate-agent/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: validate-agent
+description: Validate agent definitions for consistency, model availability, handoff integrity, and tool existence. Use this when creating or modifying agents.
+---
+
+# Validate Agent Skill
+
+## Purpose
+Ensure that agent definitions are technically sound, follow project standards, and are compatible with the current environment and other agents.
+
+## When to Use
+- After creating a new agent.
+- After modifying an existing agent's frontmatter (model, tools, handoffs).
+- When troubleshooting "dead-end" handoffs or tool execution failures.
+
+## Workflow
+
+### 1. Run Automated Validation
+Execute the validation script to check for common errors in frontmatter and structure:
+
+```bash
+./scripts/validate-agents.py
+```
+
+This script checks:
+- **Model Availability**: Verifies the model exists in `docs/ai-model-reference.md`.
+- **Handoff Integrity**: Verifies that handoff targets exist.
+- **Required Sections**: Ensures all mandatory headers are present.
+- **Snake Case Tools**: Warns about potential invalid tool names.
+
+### 2. Validate Tool Existence
+As the **Workflow Engineer**, you have access to all available tools in the workspace. You must manually verify that every tool listed in an agent's `tools:` array exists in your own tool list.
+
+- **Check**: Compare the agent's `tools:` list against your own available tools.
+- **Wildcards**: If an agent uses a wildcard (e.g., `github/*`), ensure you have tools with that prefix.
+- **Naming**: Ensure the tool IDs match exactly (case-sensitive). VS Code tools typically use `category/toolName` or `publisher.extension/toolName` format.
+
+### 3. Verify Boundary Consistency
+Check that the agent's boundaries (✅ Always Do, ⚠️ Ask First, 🚫 Never Do) are:
+- **Specific**: Use concrete commands and file paths.
+- **Actionable**: The agent can actually perform the "Always Do" actions with its tools.
+- **Consistent**: They do not contradict project-wide instructions in `.github/copilot-instructions.md`.
+
+### 4. Check Handoff Logic
+Verify that the `handoffs:` section makes sense for the agent's role:
+- Does the `prompt` provide enough context for the next agent?
+- Is `send: false` used for handoffs that require user review before proceeding? (Standard for this project).
+
+## Output
+- A summary of validation results.
+- Fixes for any identified issues.
+- Confirmation that the agent is ready for use.

docs/agents.md

@@ -86,6 +86,7 @@ Format:
 | `watch-uat-github-pr` | Watch a GitHub UAT PR for maintainer feedback or approval by polling comments until approved/passed. |
 | `watch-uat-azdo-pr` | Watch an Azure DevOps UAT PR for maintainer feedback or approval by polling threads and reviewer votes until approved/passed. |
 | `analyze-chat-export` | Extract metrics from VS Code Copilot chat exports for retrospective analysis (model usage, tool invocations, approvals, timing). |
+| `validate-agent` | Validate agent definitions for consistency, model availability, handoff integrity, and tool existence. |
 
 ### Prefer GitHub Chat Tools For PR Inspection