From 536acc868814418dcf2a92f94f850b234d4a9d7d Mon Sep 17 00:00:00 2001 From: ikrispin Date: Tue, 7 Jul 2026 18:49:00 +0300 Subject: [PATCH 1/2] Add dashboard-aware presentation to ocp-admin skills Add UI Widget Policy to AGENTS.md that directs agents to call UI-opening tools immediately when interactive widgets are available, falling back to skill workflows in text-only environments. cluster-creator: Add open_cluster_creator to allowed-tools and replace Step 1 with environment detection that calls it immediately on UI-capable clients, skipping text-based parameter gathering. cluster-inventory: Add get_cluster_hosts to allowed-tools, document dashboard auto-presentation after list_clusters, and add setup navigation tool to dependencies. --- ocp-admin/AGENTS.md | 16 ++++++++++++++++ ocp-admin/skills/cluster-creator/SKILL.md | 8 ++++---- ocp-admin/skills/cluster-inventory/SKILL.md | 7 +++++-- 3 files changed, 25 insertions(+), 6 deletions(-) diff --git a/ocp-admin/AGENTS.md b/ocp-admin/AGENTS.md index 1862f31f..32838eae 100644 --- a/ocp-admin/AGENTS.md +++ b/ocp-admin/AGENTS.md @@ -8,6 +8,20 @@ ALWAYS use the appropriate skill for OpenShift cluster administration and securi To invoke a skill, use the Skill tool with the skill name (e.g., `/cluster-creator`). +## UI Widget Policy + +When interactive UI widgets are available, prefer calling UI-opening tools immediately without gathering parameters first. The interactive form will collect all required information from the user. + +| User intent | Tool to call | What happens | +|---|---|---| +| Create a cluster, install OpenShift, deploy SNO/HA | `open_cluster_creator` | Opens the Cluster Creator form | +| List clusters, show my clusters, cluster status | `list_clusters` | Opens the Cluster Inventory dashboard | +| Set up a cluster, configure hosts, assign roles, install | `get_cluster_hosts` with the cluster ID | Opens the Cluster Setup dashboard | + +Do NOT call `create_cluster` to open the UI — it requires cluster parameters and is used for actually creating the cluster after parameters are known. For UI-based creation, always call `open_cluster_creator`. + +In text-only environments where these tools do not render UI widgets, follow the skill workflows for step-by-step parameter gathering instead. + ## Intent Routing Match the user's request to the correct skill: @@ -24,6 +38,8 @@ Match the user's request to the correct skill: If the request doesn't clearly match one skill, ask the user to clarify. +When starting a skill workflow, read the corresponding Knowledge file for the detailed step-by-step instructions — but always respect the UI Widget Policy above for the three widget flows. + ## Skill Chaining Some workflows require multiple skills in sequence: diff --git a/ocp-admin/skills/cluster-creator/SKILL.md b/ocp-admin/skills/cluster-creator/SKILL.md index 0f832060..74c17993 100644 --- a/ocp-admin/skills/cluster-creator/SKILL.md +++ b/ocp-admin/skills/cluster-creator/SKILL.md @@ -20,7 +20,7 @@ description: | license: Apache-2.0 model: inherit color: green -allowed-tools: list_versions create_cluster cluster_info set_cluster_vips set_host_role cluster_iso_download_url install_cluster cluster_credentials_download_url cluster_logs_download_url list_static_network_config generate_nmstate_yaml validate_nmstate_yaml alter_static_network_config_nmstate_for_host +allowed-tools: open_cluster_creator list_versions create_cluster cluster_info set_cluster_vips set_host_role cluster_iso_download_url install_cluster cluster_credentials_download_url cluster_logs_download_url list_static_network_config generate_nmstate_yaml validate_nmstate_yaml alter_static_network_config_nmstate_for_host metadata: mcp_server: openshift-self-managed mcp_tools_priority: true @@ -120,13 +120,13 @@ TaskCreate(subject: "#12 Retrieve credentials", description: "Download kubeconfi **During execution**: Update task status to "in_progress" when starting, "completed" when done. -### Step 1: Prerequisites Check +### Step 1: Environment Detection and Prerequisites **TaskUpdate**: Mark task #1 as `in_progress` -**Prerequisites Check**: Execute verification from Prerequisites section. +**Check for interactive UI**: If the `open_cluster_creator` tool is available, call it immediately. The interactive Creator form handles Steps 2 through 6. Once the cluster is created via the form, resume from **Step 7** using the cluster ID returned by the form. -**On Failure**: If prerequisites fail, consult [troubleshooting.md](docs/troubleshooting.md) for common setup issues, then stop and report error to user. +**Otherwise (text-only)**: Execute prerequisites verification from the Prerequisites section above, then continue to Step 2. On failure, consult [troubleshooting.md](docs/troubleshooting.md) and stop. --- diff --git a/ocp-admin/skills/cluster-inventory/SKILL.md b/ocp-admin/skills/cluster-inventory/SKILL.md index 8eea57cc..7f86f2d9 100644 --- a/ocp-admin/skills/cluster-inventory/SKILL.md +++ b/ocp-admin/skills/cluster-inventory/SKILL.md @@ -16,7 +16,7 @@ description: | license: Apache-2.0 model: inherit color: cyan -allowed-tools: list_clusters cluster_info cluster_events cluster_logs_download_url +allowed-tools: list_clusters get_cluster_hosts cluster_info cluster_events cluster_logs_download_url metadata: mcp_servers: - openshift-self-managed @@ -158,6 +158,8 @@ Do NOT use when: 3. Sort by type (OCP→ROSA→ARO→OSD→SNO), then date (newest first) 4. Display with summary header + list/table format +**Dashboard presentation**: After receiving the `list_clusters` response, the Cluster Inventory dashboard opens automatically on UI-capable clients. On text-only clients, format the results as described in Output Formatting. + **Error Handling**: - Both APIs fail → Verify OFFLINE_TOKEN and connectivity - One API fails → Show partial results with note @@ -228,7 +230,8 @@ Execute when user requests events, troubleshoots errors, or needs installation l - `openshift-ocm-managed` - OCM service for ROSA/ARO/OSD ([setup](../../README.md)) ### Required MCP Tools -- `list_clusters` (from both servers) - Lists clusters (auto-routes to correct API) +- `list_clusters` (from both servers) - Lists clusters and opens the Cluster Inventory dashboard on UI-capable clients. Falls back to text on others. +- `get_cluster_hosts` (from openshift-self-managed) - Opens the Cluster Setup dashboard for a specific cluster on UI-capable clients. - `cluster_info` (from both servers) - Gets cluster details (auto-routes to correct API) - `cluster_events` (from openshift-self-managed only) - Gets events for self-managed clusters - `cluster_logs_download_url` (from openshift-self-managed only) - Gets log download URL From 3aa9471119b2558f2c3d96177df9323ae2f192f3 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Wed, 8 Jul 2026 16:52:17 +0300 Subject: [PATCH 2/2] Mark get_cluster_hosts as optional with availability guard Add "(optional)" and "If available" guard to get_cluster_hosts in the Dependencies section, matching the pattern used for open_cluster_creator in cluster-creator skill. --- ocp-admin/skills/cluster-inventory/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ocp-admin/skills/cluster-inventory/SKILL.md b/ocp-admin/skills/cluster-inventory/SKILL.md index 7f86f2d9..9eccbd55 100644 --- a/ocp-admin/skills/cluster-inventory/SKILL.md +++ b/ocp-admin/skills/cluster-inventory/SKILL.md @@ -231,7 +231,7 @@ Execute when user requests events, troubleshoots errors, or needs installation l ### Required MCP Tools - `list_clusters` (from both servers) - Lists clusters and opens the Cluster Inventory dashboard on UI-capable clients. Falls back to text on others. -- `get_cluster_hosts` (from openshift-self-managed) - Opens the Cluster Setup dashboard for a specific cluster on UI-capable clients. +- `get_cluster_hosts` (from openshift-self-managed, optional) - If available, opens the Cluster Setup dashboard for a specific cluster on UI-capable clients. Falls back to text on others. - `cluster_info` (from both servers) - Gets cluster details (auto-routes to correct API) - `cluster_events` (from openshift-self-managed only) - Gets events for self-managed clusters - `cluster_logs_download_url` (from openshift-self-managed only) - Gets log download URL