From 1635a6362bb9a52dbaf57fce5c06b00676404229 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Sun, 1 Mar 2026 21:00:24 +0200 Subject: [PATCH 1/4] enable user skill invocation by slash command --- rh-developer/skills/containerize-deploy/SKILL.md | 2 ++ rh-developer/skills/deploy/SKILL.md | 2 ++ rh-developer/skills/detect-project/SKILL.md | 2 ++ rh-developer/skills/helm-deploy/SKILL.md | 2 ++ rh-developer/skills/recommend-image/SKILL.md | 2 ++ rh-developer/skills/rhel-deploy/SKILL.md | 2 ++ rh-developer/skills/s2i-build/SKILL.md | 2 ++ 7 files changed, 14 insertions(+) diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index a64bd459..c9532e0a 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -2,6 +2,8 @@ name: containerize-deploy description: | Complete end-to-end workflow for containerizing and deploying applications to OpenShift or standalone RHEL systems. Orchestrates /detect-project, /s2i-build, /deploy, /helm-deploy, and /rhel-deploy skills with user confirmation checkpoints at each phase. Supports S2I, Podman, Helm deployment strategies for OpenShift, and Podman/native deployments for RHEL hosts. Use this skill when user wants to go from source code to running application in one guided workflow. Supports resume after interruption and rollback on failure. Triggers on /containerize-deploy command. +metadata: + user_invocable: "true" --- # /containerize-deploy Skill diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index ab9154f4..1c4db8bc 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -2,6 +2,8 @@ name: deploy description: | Create Kubernetes Deployment, Service, and Route resources on OpenShift to deploy and expose an application. Use this skill after /s2i-build to make the built image accessible. Handles port detection, replica configuration, HTTPS route creation, rollout monitoring, and rollback on failure. Triggers on /deploy command when user wants to deploy a container image to OpenShift. +metadata: + user_invocable: "true" --- # /deploy Skill diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index 5b7d3222..8770fe0e 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -2,6 +2,8 @@ name: detect-project description: | Analyze a project folder or GitHub repository to detect programming language, framework, and version requirements. Use this skill when containerizing an application, selecting an S2I builder image, deploying to OpenShift or RHEL, or determining a project's tech stack. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl. Triggers on /detect-project command or when user needs build strategy recommendations. Run before /s2i-build or /rhel-deploy. +metadata: + user_invocable: "true" --- # /detect-project Skill diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index bafc43df..4631ba89 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -2,6 +2,8 @@ name: helm-deploy description: | Deploy applications to OpenShift using Helm charts. Use this skill when user wants to deploy with Helm, when a Helm chart is detected in the project, or when /helm-deploy command is invoked. Supports both existing charts and chart creation. Handles chart detection, values customization, install/upgrade operations, and rollback. Requires kubernetes MCP Helm tools. +metadata: + user_invocable: "true" --- # /helm-deploy Skill diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 5767a4d2..9e423c98 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -2,6 +2,8 @@ name: recommend-image description: | Intelligently recommend the optimal S2I builder image or container base image for a project based on detected language/framework, use-case requirements, security posture, and deployment target. Supports GitHub URLs for remote project analysis (delegates to /detect-project). Use this skill when the user needs a container image recommendation, wants to compare image options, or asks about production vs development images. Triggers on /recommend-image command, or when advanced image selection beyond basic version matching is needed. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl on Red Hat UBI. +metadata: + user_invocable: "true" --- # /recommend-image Skill diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index d9b62cff..661c5008 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -2,6 +2,8 @@ name: rhel-deploy description: | CRITICAL: When user types /rhel-deploy, use THIS skill immediately. This skill deploys applications to standalone RHEL/Fedora/CentOS systems (NOT OpenShift) using Podman containers with systemd, or native dnf builds. Handles SSH connectivity, SELinux, firewall-cmd, and systemd unit creation. Triggers: /rhel-deploy command, 'deploy to RHEL', 'deploy to Fedora', 'deploy to my server via SSH'. +metadata: + user_invocable: "true" --- # /rhel-deploy Skill diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index 105a9408..ad05672f 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -2,6 +2,8 @@ name: s2i-build description: | Create BuildConfig and ImageStream resources on OpenShift and trigger a Source-to-Image (S2I) build. Use this skill after /detect-project to build container images from source code on the cluster. Handles namespace verification, resource creation with user confirmation, build monitoring with log streaming, and failure recovery. Triggers on /s2i-build command. Run before /deploy. +metadata: + user_invocable: "true" --- # /s2i-build Skill From 6156d4d344634aa8f0e28cf3c1bfb696c051e573 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Mon, 2 Mar 2026 19:25:51 +0200 Subject: [PATCH 2/4] add header fields to comply with validation --- .../skills/containerize-deploy/SKILL.md | 16 +++++++++------- rh-developer/skills/debug-build/SKILL.md | 2 ++ rh-developer/skills/debug-container/SKILL.md | 2 ++ rh-developer/skills/debug-network/SKILL.md | 2 ++ rh-developer/skills/debug-pipeline/SKILL.md | 2 ++ rh-developer/skills/debug-pod/SKILL.md | 2 ++ rh-developer/skills/debug-rhel/SKILL.md | 2 ++ rh-developer/skills/deploy/SKILL.md | 8 +++++--- rh-developer/skills/detect-project/SKILL.md | 10 ++++++---- rh-developer/skills/helm-deploy/SKILL.md | 10 ++++++---- rh-developer/skills/recommend-image/SKILL.md | 18 ++++++++++-------- rh-developer/skills/rhel-deploy/SKILL.md | 18 ++++++++++-------- rh-developer/skills/s2i-build/SKILL.md | 12 +++++++----- .../skills/validate-environment/SKILL.md | 10 ++++++---- 14 files changed, 71 insertions(+), 43 deletions(-) diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index c9532e0a..bc4d119d 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -2,6 +2,8 @@ name: containerize-deploy description: | Complete end-to-end workflow for containerizing and deploying applications to OpenShift or standalone RHEL systems. Orchestrates /detect-project, /s2i-build, /deploy, /helm-deploy, and /rhel-deploy skills with user confirmation checkpoints at each phase. Supports S2I, Podman, Helm deployment strategies for OpenShift, and Podman/native deployments for RHEL hosts. Use this skill when user wants to go from source code to running application in one guided workflow. Supports resume after interruption and rollback on failure. Triggers on /containerize-deploy command. +model: inherit +color: green metadata: user_invocable: "true" --- @@ -35,7 +37,7 @@ Provide a complete, guided workflow from local source code to running applicatio ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: @@ -638,9 +640,9 @@ All tools from child skills: ## Reference Documentation For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Language detection, S2I builder images -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Image variant selection, LTS timelines -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python S2I configuration -- [docs/rhel-deployment.md](../docs/rhel-deployment.md) - RHEL host deployment (when delegating to /rhel-deploy) -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - All required tools by skill +- [docs/builder-images.md](../../docs/builder-images.md) - Language detection, S2I builder images +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection, LTS timelines +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python S2I configuration +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL host deployment (when delegating to /rhel-deploy) +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - All required tools by skill diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index e62c7284..1edf0646 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -2,6 +2,8 @@ name: debug-build description: | Diagnose OpenShift build failures including S2I builds, Docker/Podman builds, and BuildConfig issues. Automates multi-step diagnosis: BuildConfig validation, build pod logs, registry authentication, and source repository access. Use this skill when builds fail, hang, or produce unexpected results. Triggers on /debug-build command or phrases like "build failed", "S2I error", "can't pull builder image", "can't push to registry", "build timeout". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index 0669b610..3bf7eac4 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -2,6 +2,8 @@ name: debug-container description: | Diagnose local container issues with Podman/Docker including image pull errors, container startup failures, OOM kills, and networking problems. Automates multi-step diagnosis: container inspect, logs retrieval, image analysis, and resource constraint checking. Use this skill when containers fail to run locally before deployment. Triggers on /debug-container command or phrases like "container won't start", "podman run fails", "local container crashing", "container exits immediately". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index b084e790..23bd054d 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -2,6 +2,8 @@ name: debug-network description: | Diagnose OpenShift service connectivity issues including DNS resolution, service endpoints, route ingress, and network policies. Automates multi-step diagnosis: service endpoint verification, pod selector matching, route status, and network policy analysis. Use this skill when services can't communicate, routes return 503/502 errors, or external access fails. Triggers on /debug-network command or phrases like "can't reach service", "route returning 503", "pods can't communicate", "no endpoints". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index 8c8f3f6e..f8953377 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -2,6 +2,8 @@ name: debug-pipeline description: | Diagnose OpenShift Pipelines (Tekton) CI/CD failures including PipelineRun failures, TaskRun step errors, workspace/PVC binding issues, and authentication problems. Automates multi-step diagnosis: PipelineRun status, failed TaskRun analysis, step container logs, and related resource checks. Use this skill when pipelines fail, hang, or produce unexpected results. Triggers on /debug-pipeline command or phrases like "pipeline failed", "PipelineRun error", "TaskRun failed", "tekton error", "pipeline stuck", "pipeline timeout". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index ca3cb66a..9ace0952 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -2,6 +2,8 @@ name: debug-pod description: | Diagnose pod failures on OpenShift including CrashLoopBackOff, ImagePullBackOff, OOMKilled, and pending pods. Automates multi-step diagnosis: pod status, events, logs (current + previous), and resource constraint analysis. Use this skill when pods are not running, restarting frequently, or stuck in non-ready states. Triggers on /debug-pod command or phrases like "my pod is crashing", "pod won't start", "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index e62ca0e1..a0983b7a 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -2,6 +2,8 @@ name: debug-rhel description: | Diagnose RHEL system issues including systemd service failures, SELinux denials, firewall blocking, and system resource problems. Automates multi-step diagnosis: journalctl log analysis, SELinux denial detection (ausearch), firewall rule inspection, and systemd unit status. Use this skill when applications fail on standalone RHEL/Fedora/CentOS hosts deployed via /rhel-deploy. Triggers on /debug-rhel command or phrases like "service won't start on RHEL", "SELinux blocking", "systemd failed", "firewall blocking". +model: inherit +color: cyan metadata: user_invocable: "true" --- diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index 1c4db8bc..c74c0486 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -2,6 +2,8 @@ name: deploy description: | Create Kubernetes Deployment, Service, and Route resources on OpenShift to deploy and expose an application. Use this skill after /s2i-build to make the built image accessible. Handles port detection, replica configuration, HTTPS route creation, rollout monitoring, and rollback on failure. Triggers on /deploy command when user wants to deploy a container image to OpenShift. +model: inherit +color: green metadata: user_invocable: "true" --- @@ -19,7 +21,7 @@ Before running this skill: ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: 1. **Wait for user confirmation** before executing any actions @@ -395,5 +397,5 @@ Your application is now live! ## Reference Documentation For detailed guidance, see: -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc), cluster access verification -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index 8770fe0e..e34cd075 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -2,6 +2,8 @@ name: detect-project description: | Analyze a project folder or GitHub repository to detect programming language, framework, and version requirements. Use this skill when containerizing an application, selecting an S2I builder image, deploying to OpenShift or RHEL, or determining a project's tech stack. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl. Triggers on /detect-project command or when user needs build strategy recommendations. Run before /s2i-build or /rhel-deploy. +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -17,7 +19,7 @@ Analyze the project to detect language/framework and recommend a build strategy. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires user confirmation before proceeding. You MUST: 1. **Wait for user confirmation** on detected values before saving to session state @@ -305,6 +307,6 @@ Returns: Actual file content as text ## Reference Documentation For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (git) +- [docs/builder-images.md](../../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (git) diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index 4631ba89..b8b29bc9 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -2,6 +2,8 @@ name: helm-deploy description: | Deploy applications to OpenShift using Helm charts. Use this skill when user wants to deploy with Helm, when a Helm chart is detected in the project, or when /helm-deploy command is invoked. Supports both existing charts and chart creation. Handles chart detection, values customization, install/upgrade operations, and rollback. Requires kubernetes MCP Helm tools. +model: inherit +color: green metadata: user_invocable: "true" --- @@ -18,7 +20,7 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: 1. **Wait for user confirmation** before executing any actions @@ -376,6 +378,6 @@ Your application is live! ## Reference Documentation For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - Container image references for chart values -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Image variant selection for production deployments -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc, helm) +- [docs/builder-images.md](../../docs/builder-images.md) - Container image references for chart values +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection for production deployments +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc, helm) diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 9e423c98..104b6eae 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -2,6 +2,8 @@ name: recommend-image description: | Intelligently recommend the optimal S2I builder image or container base image for a project based on detected language/framework, use-case requirements, security posture, and deployment target. Supports GitHub URLs for remote project analysis (delegates to /detect-project). Use this skill when the user needs a container image recommendation, wants to compare image options, or asks about production vs development images. Triggers on /recommend-image command, or when advanced image selection beyond basic version matching is needed. Supports Node.js, Python, Java, Go, Ruby, .NET, PHP, and Perl on Red Hat UBI. +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -20,7 +22,7 @@ Provide intelligent, use-case-aware container image recommendations that go beyo ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires user input and confirmation. You MUST: 1. **Wait for user responses** to all questions before proceeding @@ -118,7 +120,7 @@ For each language, evaluate available variants against user requirements. **Key Scoring Factors:** Image size, security posture, build tools availability, startup time, LTS status -> **See [docs/image-selection-criteria.md](../docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). +> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). ### Step 3.5: Dynamic Image Validation @@ -145,7 +147,7 @@ To provide accurate image recommendations, I need `skopeo` to inspect container - Check architecture support (amd64, arm64) - Show when the image was last built -**Install skopeo:** See [docs/prerequisites.md](../docs/prerequisites.md) for installation commands by OS. +**Install skopeo:** See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. After installing, run `/recommend-image` again for enhanced recommendations. @@ -268,7 +270,7 @@ Return to Step 2 with new inputs. - **Development** → Full variant - **Serverless** → Smallest available (minimal or native binary) -> **See [docs/image-selection-criteria.md](../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). +> **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). ## Output Variables @@ -284,7 +286,7 @@ After successful recommendation: ## Reference Documentation For detailed guidance, see: -- [docs/image-selection-criteria.md](../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees -- [docs/builder-images.md](../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability -- [docs/dynamic-validation.md](../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns -- [docs/prerequisites.md](../docs/prerequisites.md) - Skopeo installation instructions +- [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees +- [docs/builder-images.md](../../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability +- [docs/dynamic-validation.md](../../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns +- [docs/prerequisites.md](../../docs/prerequisites.md) - Skopeo installation instructions diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index 661c5008..42f04dd9 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -2,6 +2,8 @@ name: rhel-deploy description: | CRITICAL: When user types /rhel-deploy, use THIS skill immediately. This skill deploys applications to standalone RHEL/Fedora/CentOS systems (NOT OpenShift) using Podman containers with systemd, or native dnf builds. Handles SSH connectivity, SELinux, firewall-cmd, and systemd unit creation. Triggers: /rhel-deploy command, 'deploy to RHEL', 'deploy to Fedora', 'deploy to my server via SSH'. +model: inherit +color: yellow metadata: user_invocable: "true" --- @@ -35,7 +37,7 @@ Deploy applications to standalone RHEL systems using Podman containers or native ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: 1. **Wait for user confirmation** before executing any actions @@ -308,7 +310,7 @@ ssh [target] "podman pull [image-reference]" | Environment | [list env vars] | | Run Mode | [rootless / rootful] | -**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for SELinux configuration details. +**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for SELinux configuration details. Proceed with this configuration? (yes/modify/cancel) ``` @@ -408,7 +410,7 @@ Proceed with firewall configuration? (yes/skip) **Runtime packages for [language]:** -See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). +See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). **Commands to execute:** ```bash @@ -475,7 +477,7 @@ Proceed with deployment? (yes/no) | `${PORT}` | [container-port] | Application listen port | | `${START_COMMAND}` | [see below] | Language-specific start command | -**Start commands by language:** See [docs/rhel-deployment.md](../docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). +**Start commands by language:** See [docs/rhel-deployment.md](../../docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). **Target location:** `/etc/systemd/system/[app-name].service` @@ -639,7 +641,7 @@ When delegating to `/recommend-image`: ## Reference Documentation For detailed guidance, see: -- [docs/rhel-deployment.md](../docs/rhel-deployment.md) - Comprehensive RHEL deployment reference: systemd unit templates, SELinux configuration, firewall commands, runtime package mapping -- [docs/selinux-troubleshooting.md](../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (ssh, podman) +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - Comprehensive RHEL deployment reference: systemd unit templates, SELinux configuration, firewall commands, runtime package mapping +- [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (ssh, podman) diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index ad05672f..f671e26b 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -2,6 +2,8 @@ name: s2i-build description: | Create BuildConfig and ImageStream resources on OpenShift and trigger a Source-to-Image (S2I) build. Use this skill after /detect-project to build container images from source code on the cluster. Handles namespace verification, resource creation with user confirmation, build monitoring with log streaming, and failure recovery. Triggers on /s2i-build command. Run before /deploy. +model: inherit +color: green metadata: user_invocable: "true" --- @@ -19,7 +21,7 @@ Before running this skill, ensure: ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: 1. **Wait for user confirmation** before executing any actions @@ -433,7 +435,7 @@ On success, these values are available for `/deploy`: ## Reference Documentation For detailed guidance, see: -- [docs/builder-images.md](../docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting -- [docs/debugging-patterns.md](../docs/debugging-patterns.md) - Common build error patterns and troubleshooting -- [docs/prerequisites.md](../docs/prerequisites.md) - Required tools (oc) +- [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping +- [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common build error patterns and troubleshooting +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc) diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index 74b97072..f358a402 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -2,6 +2,8 @@ name: validate-environment description: | Check and report the status of required tools and environment for rh-developer skills. Validates tool installation (oc, helm, podman, git, skopeo, etc.), cluster connectivity, and permissions. Use this skill before running other deployment skills to ensure prerequisites are met. Triggers on /validate-environment command or when user asks to check their environment setup. +model: inherit +color: cyan metadata: user_invocable: "true" --- @@ -12,7 +14,7 @@ Check that required tools and environment are properly configured. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. **Key Rules:** 1. WAIT for user to select validation scope before running checks @@ -66,7 +68,7 @@ check_tool() { **Tools to check:** git, curl, jq, oc, helm, podman, docker, skopeo, ssh -> **See [docs/prerequisites.md](../docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. +> **See [docs/prerequisites.md](../../docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. ### Step 3: Check OpenShift Connectivity (if TARGET includes openshift) @@ -186,7 +188,7 @@ Select an option or describe what you'd like to do: This tool is required for [skill-names]. -See [docs/prerequisites.md](../docs/prerequisites.md) for installation commands by OS. +See [docs/prerequisites.md](../../docs/prerequisites.md) for installation commands by OS. ``` ### Cluster Connection Failed @@ -233,4 +235,4 @@ Options: ## Reference Documentation For detailed guidance, see: -- [docs/prerequisites.md](../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification +- [docs/prerequisites.md](../../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification From c03e9514cd4692011f560cc584fac75924f9bcf9 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Mon, 2 Mar 2026 19:59:23 +0200 Subject: [PATCH 3/4] refactor: reduce skill verbosity and remove inferable details from skills to include only necessary ones --- .../skills/containerize-deploy/SKILL.md | 201 +--------------- rh-developer/skills/debug-build/SKILL.md | 102 +------- rh-developer/skills/debug-container/SKILL.md | 123 +--------- rh-developer/skills/debug-network/SKILL.md | 91 +------ rh-developer/skills/debug-pipeline/SKILL.md | 118 +-------- rh-developer/skills/debug-pod/SKILL.md | 94 +------- rh-developer/skills/debug-rhel/SKILL.md | 101 +------- rh-developer/skills/deploy/SKILL.md | 150 +----------- rh-developer/skills/detect-project/SKILL.md | 61 +---- rh-developer/skills/helm-deploy/SKILL.md | 47 +--- rh-developer/skills/recommend-image/SKILL.md | 23 +- rh-developer/skills/rhel-deploy/SKILL.md | 223 +++--------------- rh-developer/skills/s2i-build/SKILL.md | 77 +----- .../skills/validate-environment/SKILL.md | 20 -- 14 files changed, 109 insertions(+), 1322 deletions(-) diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index bc4d119d..1ef5d630 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -15,119 +15,21 @@ Provide a complete, guided workflow from local source code to running applicatio ## Overview ``` -[Intro] → [Detect] → [Target] → [Strategy] ──┬─→ [OpenShift Path] ─────┬─→ [Complete] - │ │ [S2I/Podman/Helm] │ - │ │ │ - │ └─→ [RHEL Path] ───────────┘ - │ (/rhel-deploy) - │ - User chooses target: - - OpenShift → Strategy selection (S2I/Podman/Helm) - - RHEL → Delegate to /rhel-deploy skill +[Intro] → [Detect] → [Target] → [Strategy] ──┬─→ [OpenShift: S2I/Podman/Helm] ──┬─→ [Complete] + └─→ [RHEL: /rhel-deploy] ──────────┘ ``` -**Deployment Targets:** -- **OpenShift** - Deploy to OpenShift/Kubernetes cluster (S2I, Podman, or Helm strategies) -- **RHEL Host** - Deploy to standalone RHEL system via SSH (delegates to /rhel-deploy) - -**OpenShift Deployment Strategies (if OpenShift target selected):** -- **S2I** - Source-to-Image build on OpenShift, then deploy (Phases 3-7) -- **Podman** - Build from Containerfile/Dockerfile on OpenShift, then deploy (Phases 3-7) -- **Helm** - Deploy using Helm chart (Phase 2-H) - ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: - -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next phase until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation, builds, or deployments -5. **Never skip configuration questions** even if user seems to know what they want - -If the user says "no" or wants modifications, address their concerns before proceeding. - -### Anti-Patterns to Avoid - -**CRITICAL - DO NOT DO THIS:** - -- If user says "yes do helm deployment to namespace X" - do NOT skip configuration questions -- If user seems experienced or decisive - do NOT assume they've considered all options -- If user provides strategy choice early - do NOT skip environment type question -- If user gives multiple answers at once - still ask each checkpoint question individually - -**The user specifying WHAT to deploy does not mean they've decided HOW to configure it.** - -Strategy choice ≠ Configuration approval. Always ask: -1. Environment type (dev/staging/prod) -2. Resource limits appropriate for environment -3. Runtime vs build-time configuration -4. Replicas and scaling -5. Any customizations before proceeding - -## Phase Execution Rules - -**MANDATORY:** Execute phases in order. Each phase MUST: - -1. Display the phase information to the user -2. Ask the specific question for that phase -3. Wait for user response -4. Only then proceed to next phase - -**Even if user provides information for multiple phases at once:** -- Acknowledge what they said -- But still display each phase's confirmation prompt -- Get explicit "yes" for each phase before executing - -Example: -- User: "yes do helm to test-app namespace" -- AI: "Great, you've chosen Helm strategy and test-app namespace. Let me confirm the configuration details..." -- [Still show Phase 1.7 Configuration Review] -- [Still ask environment type, config approach, etc.] - ## Workflow ### Phase 0: Introduction -```markdown -# Containerize & Deploy - -I'll help you containerize and deploy your application to OpenShift or a standalone RHEL system. - -**What this workflow does:** -1. **Detect** - Analyze your project and determine the best deployment strategy -2. **Choose Target** - Deploy to OpenShift cluster or RHEL host -3. **Build** - Build container image (S2I or Podman) or skip if using Helm with existing image -4. **Deploy** - Deploy using Kubernetes resources, Helm chart, or systemd services - -**Deployment Targets:** -- **OpenShift** - Deploy to OpenShift/Kubernetes cluster -- **RHEL Host** - Deploy directly to a RHEL system via SSH +Present the workflow overview and available deployment targets/strategies. Ask: **Ready to begin?** (yes/no) -**OpenShift Strategies:** -- **S2I (Source-to-Image)** - Build and deploy from source code -- **Podman** - Build from existing Containerfile/Dockerfile -- **Helm** - Deploy using Helm chart - -**RHEL Strategies:** -- **Container** - Run with Podman + systemd -- **Native** - Install with dnf + systemd - -**What I need from you:** -- Confirmation at each step before I make changes -- Access to an OpenShift cluster OR SSH access to a RHEL host -- Your project source code - -**Ready to begin?** (yes/no) -``` - -**WAIT for user confirmation before proceeding.** Do NOT continue to Phase 1 until user explicitly confirms. - -- If user says "yes" → Proceed to Phase 1 -- If user says "no" → Ask what concerns they have -- If user gives multiple answers at once (e.g., "yes helm to namespace X") → Acknowledge their choices but still proceed through each phase individually +**WAIT for user confirmation before proceeding.** ### Phase 1: Project Detection @@ -173,7 +75,7 @@ Where would you like to deploy this application? Store `DEPLOYMENT_TARGET` in session state. -**WAIT for user confirmation before proceeding.** Do NOT assume target based on earlier statements. +**WAIT for user confirmation before proceeding.** **If user selects "RHEL":** - Store `DEPLOYMENT_TARGET = "rhel"` in session state @@ -213,7 +115,7 @@ Based on my analysis, you have these options: Store `DEPLOYMENT_STRATEGY` in session state. -**WAIT for user confirmation before proceeding.** Do NOT skip to Phase 1.7 without explicit strategy selection. +**WAIT for user confirmation before proceeding.** ### Phase 1.6: Image Selection (S2I/Podman only) @@ -292,10 +194,7 @@ Before I proceed, let me confirm the deployment configuration: 2. Customize resources ``` -**WAIT for user to answer ALL questions above before proceeding.** Do NOT continue to Phase 2 until user has confirmed: -- Environment type -- Configuration approach -- Resource settings +**WAIT for user to answer ALL questions above before proceeding.** Store: `ENVIRONMENT_TYPE`, `CONFIG_APPROACH`, `RESOURCE_PROFILE` in session state. @@ -547,86 +446,12 @@ Proceeding with Helm deployment... ### Phase 8: Completion -```markdown -## Deployment Complete! - -Your application is now running on OpenShift. - ---- - -**Application Summary:** - -| Setting | Value | -|---|---| -| Name | [app-name] | -| Namespace | [namespace] | -| Language | [language] | -| Framework | [framework] | - ---- - -**Access URLs:** - -| Type | URL | -|---|-----| -| **External** | https://[route-host] | -| Internal | http://[app-name].[namespace].svc.cluster.local:[port] | - ---- - -**Resources Created:** - -| Resource | Name | Status | -|----|---|-----| -| ImageStream | [app-name] | Ready | -| BuildConfig | [app-name] | Ready | -| Deployment | [app-name] | 1/1 Running | -| Service | [app-name] | Active | -| Route | [app-name] | Admitted | - ---- - -**Quick Commands:** - -```bash -# View logs -oc logs -f deployment/[app-name] -n [namespace] - -# Scale up -oc scale deployment/[app-name] --replicas=3 -n [namespace] - -# Trigger rebuild (after code changes) -oc start-build [app-name] -n [namespace] - -# Delete everything -oc delete all -l app=[app-name] -n [namespace] -``` - ---- - -**Next Steps:** -- Open your app: [route-url] -- Set up Git webhooks for automatic builds -- Add environment variables: `oc set env deployment/[app-name] KEY=value` -- Configure autoscaling: `oc autoscale deployment/[app-name] --min=1 --max=5` - ---- - -Congratulations! Your application is live. -``` - -## MCP Tools Used - -All tools from child skills: - -| Phase | Tools | -|---|---| -| Detect | `run_terminal_cmd` (optional clone) | -| Connect | `resources_list` (namespaces) | -| Build | `resources_create_or_update`, `pod_logs`, `events_list` | -| Deploy | `resources_create_or_update`, `pod_list`, `pod_logs` | -| Helm | `helm_install`, `helm_upgrade`, `helm_status`, `helm_list`, `pods_list` | -| Rollback | `resources_delete`, `helm_uninstall`, `helm_rollback` | +Present a summary including: +- Application name, namespace, language, framework +- Access URLs (external route, internal service DNS) +- Resources created with status (ImageStream, BuildConfig, Deployment, Service, Route) +- Quick commands: view logs, scale, rebuild, delete +- Next steps: open app URL, set up webhooks, add env vars, configure autoscaling ## Related Skills diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index 1edf0646..6f6bd7f0 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -23,36 +23,6 @@ Before running this skill: See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands - -## Trigger - -- User types `/debug-build` -- User says "build failed", "S2I error", "build won't complete" -- User says "can't pull builder image", "can't push to registry" -- User says "build timeout", "build stuck", "assemble failed" -- After `/s2i-build` reports a failure - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `BUILD_NAME` | Name of specific build to debug | Latest failed build | -| `BUILDCONFIG_NAME` | BuildConfig to analyze | Auto-detect | -| `NAMESPACE` | Target namespace | Current namespace | - ## Workflow ### Step 1: Identify Target Build @@ -73,7 +43,7 @@ Which build would you like me to debug? Select an option or enter a build name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target build. +**WAIT for user confirmation before proceeding.** If user selects "List failed builds": Use kubernetes MCP `resources_list` for builds, filter by Failed phase: @@ -322,70 +292,7 @@ Select an option: ## Build Failure Categories -### Common S2I Build Failures - -| Phase | Failure Type | Key Indicators | Common Fix | -|-------|--------------|----------------|------------| -| **fetch-source** | Auth failure | 401/403 in logs | Add/fix source secret | -| **fetch-source** | Repo not found | 404 in logs | Check git URL | -| **pull-builder** | Image not found | ImagePullBackOff | Import builder image | -| **pull-builder** | Auth failure | unauthorized | Add pull secret | -| **assemble** | Dependency error | npm ERR, pip error | Fix package.json/requirements | -| **assemble** | Build script fail | Non-zero exit | Check application code | -| **assemble** | Out of memory | OOMKilled | Increase build resources | -| **push** | Registry auth | unauthorized | Check push secret | -| **push** | Registry full | quota exceeded | Clean up old images | - -### Python S2I Specific Issues - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Wrong entry point | "No module named app" | Set APP_MODULE or rename to app.py | -| Missing gunicorn | "gunicorn: command not found" | Add gunicorn to requirements.txt | -| Version mismatch | Import errors | Match Python version to builder | - -See [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) for detailed Python guidance. - -### Node.js S2I Specific Issues - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Build script missing | "npm run build" fails | Add build script or set NPM_RUN | -| Node version mismatch | Syntax errors | Match engines.node in package.json | -| Private npm registry | 401 Unauthorized | Configure .npmrc or NPM_MIRROR | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | List builds, find failed builds | -| `resources_get` | Get Build spec, BuildConfig details | -| `pod_logs` | Get build pod logs | -| `events_list` | Get build events | -| `resources_list` | Check secrets, imagestreams | -| `get_file_contents` (github) | Verify source repository access | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `BUILD_NAME` | Debugged build name | `myapp-1` | -| `BUILDCONFIG_NAME` | Associated BuildConfig | `myapp` | -| `BUILD_NAMESPACE` | Namespace | `my-project` | -| `FAILURE_PHASE` | Phase where build failed | `assemble` | -| `FAILURE_CATEGORY` | Categorized failure type | `DependencyError` | -| `ROOT_CAUSE` | Identified root cause | `npm package not found` | - -## Dependencies - -### Required MCP Servers -- `openshift` (kubernetes MCP server) -- `github` (optional, for source repository verification) - -### Related Skills -- `/s2i-build` - To retry build after fixing issues -- `/debug-pod` - To debug the builder pod directly -- `/detect-project` - To re-analyze project and builder image selection +For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). ## Reference Documentation @@ -394,3 +301,8 @@ For detailed guidance, see: - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification + +**Related Skills:** +- `/s2i-build` - To retry build after fixing issues +- `/debug-pod` - To debug the builder pod directly +- `/detect-project` - To re-analyze project and builder image selection diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index 3bf7eac4..902601b4 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -35,35 +35,6 @@ Diagnose local Podman/Docker container issues by automatically gathering contain See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load Podman MCP tools (e.g., `+podman container_inspect`) before diagnostic actions -2. **Use MCP when available** - Prefer `container_list`, `container_inspect`, `container_logs` over `podman`/`docker` commands - -## Trigger - -- User types `/debug-container` -- User says "container won't start", "podman run fails" -- User says "container exits immediately", "container crashing" -- User says "can't pull image", "image not found" -- User says "OOM", "out of memory", "exit code 137" - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `CONTAINER` | Container name or ID | Auto-detect from recent | -| `IMAGE` | Image name to debug | From container | - ## Workflow ### Step 1: Identify Target Container @@ -81,7 +52,7 @@ What would you like me to debug? Select an option or enter a container name/ID: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target. +**WAIT for user confirmation before proceeding.** If user selects "List containers": Use Podman MCP `container_list`: @@ -98,7 +69,7 @@ Use Podman MCP `container_list`: Which container would you like me to debug? ``` -**WAIT for user to select a container.** +**WAIT for user confirmation before proceeding.** ### Step 2: Inspect Container @@ -310,17 +281,7 @@ Continue to diagnosis summary? (yes/no) - Evidence: [from logs] - Impact: [application cannot access data] -### Exit Code Reference - -| Exit Code | Meaning | Your Container | -|-----------|---------|----------------| -| 0 | Success | [match?] | -| 1 | General error | [match?] | -| 126 | Permission problem | [match?] | -| 127 | Command not found | [match?] | -| 137 | SIGKILL (OOM) | [match?] | -| 139 | Segfault | [match?] | -| 143 | SIGTERM | [match?] | +See [debugging-patterns.md](../../docs/debugging-patterns.md) for exit code reference. ### Recommended Actions @@ -363,84 +324,12 @@ Select an option: **WAIT for user to select next action.** -## Exit Code Reference - -| Exit Code | Signal | Meaning | Common Cause | -|-----------|--------|---------|--------------| -| 0 | - | Success | Normal exit | -| 1 | - | General error | Application error, unhandled exception | -| 2 | - | Misuse of shell | Invalid arguments | -| 126 | - | Permission denied | Cannot execute entrypoint | -| 127 | - | Command not found | Entrypoint binary missing | -| 128+N | Signal N | Killed by signal | See signal table | -| 137 | SIGKILL (9) | Force killed | OOM kill, `podman kill` | -| 139 | SIGSEGV (11) | Segmentation fault | Memory corruption | -| 143 | SIGTERM (15) | Terminated | `podman stop`, graceful shutdown | - -## Common Container Issues - -### Startup Failures - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Missing entrypoint | Exit 127 | "executable not found" | Check ENTRYPOINT/CMD | -| Wrong command | Exit 127 | "no such file" | Verify command path | -| Permission denied | Exit 126 | "permission denied" | Check file permissions | -| Missing dependency | Exit 1 | "cannot find module" | Add dependency to image | -| Port conflict | Exit 1 | "address in use" | Use different port | - -### Runtime Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| OOM killed | Exit 137 | OOMKilled=true | Increase memory limit | -| Volume permission | Exit 1 | "permission denied" | Use :Z/:z labels or fix perms | -| Missing env var | Exit 1 | "undefined" errors | Add -e VAR=value | -| Network issue | Exit 1 | "connection refused" | Check network mode | - -### SELinux Volume Issues - -On RHEL/Fedora with SELinux, volume mounts may need labels: - -```bash -# Shared label (multiple containers can access) -podman run -v /host/path:/container/path:z [image] - -# Private label (only this container) -podman run -v /host/path:/container/path:Z [image] -``` - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `container_list` | List containers | -| `container_inspect` | Get container details | -| `container_logs` | Get container output | -| `image_list` | Check image info | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `CONTAINER_ID` | Container ID | `abc123def456` | -| `CONTAINER_NAME` | Container name | `myapp` | -| `CONTAINER_IMAGE` | Image used | `myapp:latest` | -| `EXIT_CODE` | Exit code | `137` | -| `OOM_KILLED` | OOM status | `true` / `false` | -| `ROOT_CAUSE` | Identified cause | `Out of memory` | - -## Dependencies - -### Required MCP Servers -- `podman` (Podman MCP server) - -### Related Skills -- `/debug-rhel` - For systemd service issues on RHEL hosts -- `/recommend-image` - To select a better base image +For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](../../docs/debugging-patterns.md). ## Reference Documentation For detailed guidance, see: - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns, exit codes - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (podman) +- `/debug-rhel` - For systemd service issues on RHEL hosts +- `/recommend-image` - To select a better base image diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index 23bd054d..1a2f4853 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -23,36 +23,6 @@ Before running this skill: See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands - -## Trigger - -- User types `/debug-network` -- User says "can't reach service", "service not working" -- User says "route returning 503", "502 Bad Gateway" -- User says "pods can't communicate", "network timeout" -- User says "no endpoints", "service has no backends" - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `SERVICE_NAME` | Service to debug | Auto-detect | -| `ROUTE_NAME` | Route to debug | Same as service | -| `NAMESPACE` | Target namespace | Current namespace | - ## Workflow ### Step 1: Identify Target Service @@ -341,66 +311,11 @@ Select an option: ## Common Connectivity Issues -### Service Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| No endpoints | Connection refused | Empty endpoints list | Fix selector or pod labels | -| Selector mismatch | Some pods missing | Compare selector to labels | Update selector or labels | -| Wrong port | Connection refused | Check targetPort | Update service port mapping | -| Pod not ready | Intermittent failures | Readiness probe failing | Fix application or probe | - -### Route Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| 503 Service Unavailable | No healthy backends | Check endpoints | Ensure pods are ready | -| 502 Bad Gateway | Backend connection error | Pod crash or wrong port | Debug pod or fix port | -| 404 Not Found | Route not admitted | Check route status | Fix hostname conflict | -| TLS errors | Certificate issues | Check TLS config | Update certificates | -| Host not found | DNS issue | Check route host | Verify wildcard DNS | - -### Network Policy Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Ingress blocked | Connection timeout | Check policy rules | Add ingress rule | -| Egress blocked | Can't reach external | Check egress rules | Add egress rule | -| Cross-namespace blocked | Namespace isolation | Check namespaceSelector | Add namespace rule | -| Port blocked | Specific port fails | Check port rules | Add port to policy | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_get` | Get Service, Route, NetworkPolicy details | -| `resources_list` | List services, endpoints, pods, policies | -| `pod_list` | Check pod status and labels | -| `events_list` | Get route/service events | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `SERVICE_NAME` | Debugged service | `myapp` | -| `SERVICE_NAMESPACE` | Namespace | `my-project` | -| `HAS_ENDPOINTS` | Endpoints exist | `true` / `false` | -| `ENDPOINTS_READY` | Ready endpoint count | `2` | -| `ROUTE_ADMITTED` | Route status | `true` / `false` | -| `NETWORK_POLICY_BLOCKING` | Policy blocking traffic | `true` / `false` | -| `ROOT_CAUSE` | Identified root cause | `Selector mismatch` | - -## Dependencies - -### Required MCP Servers -- `openshift` (kubernetes MCP server) - -### Related Skills -- `/debug-pod` - To debug specific backend pods -- `/deploy` - To fix and redeploy the service +For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). ## Reference Documentation -For detailed guidance, see: - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- `/debug-pod` - To debug specific backend pods +- `/deploy` - To fix and redeploy the service diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index f8953377..f2a60d76 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -20,24 +20,6 @@ Before running this skill: 3. OpenShift Pipelines operator is installed on the cluster 4. PipelineRun name is known (or can be identified from recent runs) -## Critical: Human-in-the-Loop Requirements - -See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. - -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift resources_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `resources_get`, `resources_list`, `pod_logs`, `events_list` over `oc`/`kubectl` commands - ### Tekton CRD Access via MCP Tekton resources are standard Kubernetes CRDs. Use the generic MCP tools with these parameters: @@ -53,22 +35,9 @@ Tekton resources are standard Kubernetes CRDs. Use the generic MCP tools with th | TriggerTemplate | `TriggerTemplate` | `triggers.tekton.dev/v1beta1` | | TriggerBinding | `TriggerBinding` | `triggers.tekton.dev/v1beta1` | -## Trigger - -- User types `/debug-pipeline` -- User says "pipeline failed", "PipelineRun failed", "PipelineRun error" -- User says "TaskRun failed", "task step failed", "tekton error" -- User says "pipeline stuck", "pipeline timeout", "pipeline hanging" -- User says "CI/CD failed", "CI pipeline broken" -- After a CI/CD pipeline reports a failure - -## Input Parameters +## Critical: Human-in-the-Loop Requirements -| Parameter | Description | Default | -|-----------|-------------|---------| -| `PIPELINERUN_NAME` | Name of specific PipelineRun to debug | Latest failed PipelineRun | -| `PIPELINE_NAME` | Pipeline name to find runs for | Auto-detect | -| `NAMESPACE` | Target namespace | Current namespace | +See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -90,7 +59,7 @@ Which PipelineRun would you like me to debug? Select an option or enter a PipelineRun name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target PipelineRun. +**WAIT for user confirmation before proceeding.** If user selects "List failed PipelineRuns": Use kubernetes MCP `resources_list` with kind `PipelineRun`, filter by Failed status: @@ -315,84 +284,13 @@ Select an option: ## Pipeline Failure Reference -### Failure Categories - -| Category | Failure Type | Key Indicators | Common Fix | -|----------|--------------|----------------|------------| -| **Authentication** | git-clone auth | `could not read Username`, `Permission denied (publickey)` | Add git secret to ServiceAccount | -| **Authentication** | Image push | `unauthorized: access denied` | Add dockerconfigjson secret to ServiceAccount | -| **Workspace** | PVC not bound | `persistentvolumeclaim "X" not found` | Create PVC or use emptyDir | -| **Workspace** | Permission denied | `permission denied` in step logs | Check fsGroup, runAsUser, PVC access mode | -| **Workspace** | Contention | Parallel tasks fail on RWO PVC | Use RWX PVC or separate workspaces | -| **Timeout** | PipelineRun timeout | `PipelineRunTimeout` condition | Increase `spec.timeouts.pipeline` | -| **Timeout** | TaskRun timeout | `TaskRunTimeout` condition | Increase `spec.timeouts.tasks` | -| **Parameter** | Missing param | `missing required parameter` | Add param to PipelineRun spec | -| **Task Step** | Build/test failure | Non-zero exit in step | Check step logs for specific error | -| **Resource** | Pod scheduling | `FailedScheduling` event | Increase quotas or reduce step resource requests | -| **Image** | Step image pull | `ImagePullBackOff` on step container | Fix step image reference or add pull secret | -| **Pipeline** | Task not found | `task "X" not found` | Verify Task name, kind (Task vs ClusterTask), namespace | -| **Trigger** | EventListener down | No PipelineRuns created | Check EventListener pod logs | -| **Trigger** | Binding mismatch | Wrong params extracted | Fix TriggerBinding param paths in CEL expressions | - -### git-clone Task Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Private repo, no credentials | `could not read Username` | Add `kubernetes.io/basic-auth` secret annotated with `tekton.dev/git-0: https://github.com` to SA | -| SSH key missing | `Permission denied (publickey)` | Add `kubernetes.io/ssh-auth` secret annotated with `tekton.dev/git-0: github.com` to SA | -| Branch not found | `couldn't find remote ref` | Verify `revision` parameter | - -### buildah/kaniko Task Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Containerfile not found | `unable to open Containerfile/Dockerfile` | Check `DOCKERFILE` parameter path relative to workspace | -| Base image pull | `unauthorized` or `not found` for FROM image | Fix base image ref or add pull secret | -| Build context wrong | `file not found` during COPY/ADD | Fix `CONTEXT` parameter to correct subdirectory | - -### Image Push Failures - -| Issue | Symptom | Solution | -|-------|---------|----------| -| Registry auth | `unauthorized: access denied` | Add `kubernetes.io/dockerconfigjson` secret annotated with `tekton.dev/docker-0: ` to SA | -| Registry unreachable | `connection refused` / `no such host` | Check registry URL, network policies, egress rules | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | List PipelineRuns, TaskRuns, PVCs, Secrets, Pipelines, Tasks | -| `resources_get` | Get PipelineRun details, TaskRun details, Pipeline/Task definitions, ServiceAccount, EventListener | -| `pod_logs` | Get TaskRun pod logs for failed step containers (use container name `step-`) | -| `pod_list` | Find TaskRun pods | -| `events_list` | Get PipelineRun/TaskRun pod events for scheduling and binding errors | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `PIPELINERUN_NAME` | Debugged PipelineRun name | `build-and-deploy-run-abc123` | -| `PIPELINE_NAME` | Associated Pipeline | `build-and-deploy` | -| `PIPELINE_NAMESPACE` | Namespace | `my-project` | -| `FAILED_TASKRUN` | Name of the failed TaskRun | `build-and-deploy-run-abc123-build-task` | -| `FAILED_STEP` | Step that failed | `build-push` | -| `FAILURE_CATEGORY` | Categorized failure type | `Authentication` | -| `ROOT_CAUSE` | Identified root cause | `git-clone unauthorized - missing git secret on ServiceAccount` | - -## Dependencies - -### Required MCP Servers -- `openshift` (kubernetes MCP server) -- `github` (optional, for source repository verification) - -### Related Skills -- `/debug-pod` - To debug TaskRun pods directly -- `/debug-build` - If the pipeline uses OpenShift Build tasks -- `/debug-network` - If pipeline tasks fail due to network issues -- `/validate-environment` - To verify OpenShift and pipeline operator setup +For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). ## Reference Documentation -For detailed guidance, see: - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- `/debug-pod` - To debug TaskRun pods directly +- `/debug-build` - If the pipeline uses OpenShift Build tasks +- `/debug-network` - If pipeline tasks fail due to network issues +- `/validate-environment` - To verify OpenShift and pipeline operator setup diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index 9ace0952..dd82ee62 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -23,35 +23,6 @@ Before running this skill: See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation actions without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - -## Critical: Prefer MCP Tools - -**IMPORTANT:** Prefer MCP tools over CLI commands for better integration and user experience: -1. **Search for MCP tools first** - Use `ToolSearch` to load OpenShift MCP tools (e.g., `+openshift pods_get`) before diagnostic actions -2. **Use MCP when available** - Prefer `pods_get`, `pods_log`, `events_list`, `resources_get` over `oc`/`kubectl` commands - -## Trigger - -- User types `/debug-pod` -- User says "my pod is crashing", "pod won't start", "CrashLoopBackOff" -- User says "ImagePullBackOff", "OOMKilled", "pod stuck pending" -- User says "container terminated", "pod restarting" - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `POD_NAME` | Name of pod to debug | Auto-detect from failed deployment | -| `NAMESPACE` | Target namespace | Current namespace | -| `CONTAINER` | Specific container (for multi-container pods) | All containers | - ## Workflow ### Step 1: Identify Target Pod @@ -72,7 +43,7 @@ Which pod would you like me to debug? Select an option or enter a pod name: ``` -**WAIT for user response.** Do NOT proceed until user identifies the target pod. +**WAIT for user confirmation before proceeding.** If user selects "List failing pods": Use kubernetes MCP `pod_list` with namespace, then filter to show pods NOT in Running/Succeeded state: @@ -89,7 +60,7 @@ Use kubernetes MCP `pod_list` with namespace, then filter to show pods NOT in Ru Which pod would you like me to debug? ``` -**WAIT for user to select a pod.** +**WAIT for user confirmation before proceeding.** ### Step 2: Get Pod Status Overview @@ -266,65 +237,14 @@ Would you like me to: Select an option: ``` -**WAIT for user to select next action.** - -## Error Patterns Reference - -### Common Pod Failure Categories - -| Status | Likely Cause | Key Indicators | -|--------|--------------|----------------| -| **CrashLoopBackOff** | Application crash | Non-zero exit code, error in logs | -| **ImagePullBackOff** | Image access issue | Unauthorized, not found, registry timeout | -| **Pending** | Scheduling issue | Insufficient resources, node selector, taints | -| **OOMKilled** | Memory exhaustion | Exit code 137, memory limit reached | -| **CreateContainerError** | Container config issue | Invalid command, missing secrets/configmaps | -| **Init:Error** | Init container failed | Check init container logs | - -### Exit Code Reference - -| Exit Code | Meaning | Common Cause | -|-----------|---------|--------------| -| 0 | Success | Normal termination | -| 1 | General error | Application error, exception | -| 126 | Permission denied | Cannot execute entrypoint | -| 127 | Command not found | Invalid entrypoint/command | -| 137 | SIGKILL (OOM) | Memory limit exceeded | -| 139 | SIGSEGV | Segmentation fault | -| 143 | SIGTERM | Graceful shutdown | - -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `pod_list` | List pods, find failing pods | -| `resources_get` | Get pod spec, container status, node info | -| `events_list` | Get pod events for scheduling/pull/mount errors | -| `pod_logs` | Get current and previous container logs | -| `resources_list` | Check related resources (secrets, configmaps, PVCs) | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `POD_NAME` | Debugged pod name | `myapp-5d4f7b8c9-x2k4l` | -| `POD_NAMESPACE` | Pod namespace | `my-project` | -| `FAILURE_CATEGORY` | Categorized failure type | `OOMKilled`, `ImagePull`, `Scheduling` | -| `ROOT_CAUSE` | Identified root cause | `Memory limit 512Mi too low for Java app` | -| `REMEDIATION` | Suggested fix | `Increase memory limit to 1Gi` | - -## Dependencies - -### Required MCP Servers -- `openshift` (kubernetes MCP server) +**WAIT for user confirmation before proceeding.** -### Related Skills -- `/debug-build` - If pod failure is due to bad image from build -- `/debug-network` - If pod is running but service connectivity fails -- `/deploy` - To redeploy after fixing issues +For pod failure categories and exit code reference, see [debugging-patterns.md](../../docs/debugging-patterns.md). ## Reference Documentation -For detailed guidance, see: - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +- `/debug-build` - If pod failure is due to bad image from build +- `/debug-network` - If pod is running but service connectivity fails +- `/deploy` - To redeploy after fixing issues diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index a0983b7a..0bb19be7 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -35,34 +35,10 @@ Diagnose RHEL system issues by automatically gathering systemd status, journal l See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing diagnostic commands -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present findings clearly** and ask if user wants deeper analysis -4. **Never auto-execute** remediation commands without user approval - -If the user says "no" or wants to focus on specific areas, address their concerns before proceeding. - ## Note: SSH/Bash Required This skill operates on **remote RHEL hosts** via SSH, not local MCP servers. Unlike OpenShift/Podman skills, direct Bash commands with SSH are the correct approach here since MCP servers run locally and cannot access remote systems. -## Trigger - -- User types `/debug-rhel` -- User says "service won't start on RHEL", "systemd failed" -- User says "SELinux blocking", "AVC denied" -- User says "firewall blocking", "can't access port" -- User says "permission denied on RHEL" -- After `/rhel-deploy` reports a failure - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `RHEL_HOST` | SSH target (user@host) | From session state | -| `SERVICE_NAME` | systemd service to debug | Auto-detect | - ## Workflow ### Phase 1: SSH Connection @@ -457,78 +433,7 @@ Select an option: **WAIT for user to select next action.** -## Common RHEL Issues - -### systemd Service Issues - -| Issue | Symptom | Diagnosis | Fix | -|-------|---------|-----------|-----| -| Unit not found | "not-found" load state | Service file missing | Create or install unit file | -| Exit code 1 | "failed" status | Application error | Check application logs | -| Exit code 126 | Permission issue | Cannot execute | Check ExecStart path/perms | -| Exit code 127 | Command not found | Binary missing | Install dependency | -| Exit code 203 | Exec format error | Wrong architecture | Rebuild for target arch | -| Exit code 217 | User not found | Bad User= directive | Create user or fix unit | - -### SELinux Common Denials - -| Denial Type | Symptom | Common Fix | -|-------------|---------|------------| -| Port binding | Cannot bind to port | `semanage port -a -t http_port_t -p tcp [port]` | -| File read | Cannot read config | `semanage fcontext` + `restorecon` | -| File write | Cannot write data | `semanage fcontext` + `restorecon` | -| Network connect | Cannot connect out | `setsebool -P httpd_can_network_connect on` | -| Container | Podman issues | `setsebool -P container_manage_cgroup on` | - -See [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) for detailed guidance. - -### Firewall Issues - -| Issue | Symptom | Fix | -|-------|---------|-----| -| Port not open | Connection refused from outside | `firewall-cmd --add-port=[port]/tcp` | -| Service not enabled | Standard service blocked | `firewall-cmd --add-service=[service]` | -| Zone mismatch | Rules in wrong zone | Check active zone, add to correct zone | -| Rich rule blocking | Specific traffic blocked | Review/remove rich rules | - -## MCP Tools Used - -This skill primarily uses Bash (SSH commands) since it operates on remote RHEL hosts. - -**Optional Lightspeed MCP tools** (used in Phase 7 if `lightspeed-mcp` is available): - -| Tool | Purpose | -|------|---------| -| `find_host_by_name` | Look up the target system in Red Hat Insights inventory | -| `get_system_cves` | Get CVEs affecting the specific system | -| `get_active_rules` | Get advisor configuration recommendations | -| `get_rule_by_text_search` | Search advisor recommendations by error text from logs | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `RHEL_HOST` | Target host | `user@192.168.1.100` | -| `SERVICE_NAME` | Debugged service | `myapp.service` | -| `SERVICE_STATUS` | Current status | `failed` | -| `SELINUX_DENIALS` | AVC denial count | `3` | -| `FIREWALL_BLOCKING` | Port blocked | `true` / `false` | -| `ROOT_CAUSE` | Identified root cause | `SELinux port binding denied` | -| `INSIGHTS_SYSTEM_ID` | Insights system ID (if registered) | `abc-def-123` | -| `CVE_COUNT` | Number of CVEs affecting system | `3` | - -## Dependencies - -### Required Tools -- SSH client with key-based authentication -- sudo access on target host - -### Optional MCP Servers -- `lightspeed-mcp` - Red Hat Insights vulnerability, advisor, and inventory data (Phase 7) - -### Related Skills -- `/rhel-deploy` - To redeploy after fixing issues -- `/debug-container` - To debug Podman containers on the host +For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](../../docs/debugging-patterns.md) and [selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md). ## Reference Documentation @@ -537,3 +442,7 @@ For detailed guidance, see: - [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL deployment patterns - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools and setup + +**Related Skills:** +- `/rhel-deploy` - To redeploy after fixing issues +- `/debug-container` - To debug Podman containers on the host diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index c74c0486..13a69e58 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -23,14 +23,6 @@ Before running this skill: See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation or deployments - -If the user says "no" or wants modifications, address their concerns before proceeding. - ## Workflow ### Step 1: Gather Deployment Information @@ -55,7 +47,7 @@ If the user says "no" or wants modifications, address their concerns before proc Confirm these settings or tell me what to change. ``` -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms these settings or provides corrections. +**WAIT for user confirmation before proceeding.** ### Step 2: Detect Container Port @@ -81,7 +73,7 @@ Is this correct? - no - Specify the correct port ``` -**WAIT for user confirmation.** Do NOT proceed until user confirms the port or provides the correct value. +**WAIT for user confirmation before proceeding.** If unable to detect: ```markdown @@ -106,67 +98,14 @@ Show the Deployment manifest: ```markdown ## Step 1 of 3: Create Deployment -A Deployment manages your application pods. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] - app.kubernetes.io/name: [app-name] - annotations: - image.openshift.io/triggers: | - [{"from":{"kind":"ImageStreamTag","name":"[app-name]:latest"},"fieldPath":"spec.template.spec.containers[0].image"}] -spec: - replicas: [replicas] - selector: - matchLabels: - app: [app-name] - template: - metadata: - labels: - app: [app-name] - spec: - containers: - - name: [app-name] - image: image-registry.openshift-image-registry.svc:5000/[namespace]/[app-name]:latest - ports: - - containerPort: [port] - protocol: TCP - resources: - requests: - memory: "128Mi" - cpu: "100m" - limits: - memory: "512Mi" - cpu: "500m" - livenessProbe: - httpGet: - path: / - port: [port] - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - httpGet: - path: / - port: [port] - initialDelaySeconds: 5 - periodSeconds: 5 -``` +Read `templates/deployment.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`, `${PORT}`, `${REPLICAS}` with session state values. -**This Deployment will:** -- Run [replicas] replica(s) of your application -- Use image from ImageStream: `[app-name]:latest` -- Expose container port: [port] -- Auto-update when new images are pushed +Show the rendered YAML to user and confirm. **Proceed with creating this Deployment?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the Deployment until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "no" → Ask what they would like to change @@ -177,35 +116,14 @@ spec: ```markdown ## Step 2 of 3: Create Service -A Service provides internal load balancing to your pods. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] -spec: - selector: - app: [app-name] - ports: - - name: http - port: [port] - targetPort: [port] - protocol: TCP - type: ClusterIP -``` +Read `templates/service.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`, `${PORT}`. -**This Service will:** -- Create internal DNS: `[app-name].[namespace].svc.cluster.local` -- Load balance traffic to pods on port [port] +Show the rendered YAML to user and confirm. **Proceed with creating this Service?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the Service until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "no" → Ask what they would like to change @@ -218,38 +136,14 @@ If user wants external exposure: ```markdown ## Step 3 of 3: Create Route -A Route exposes your application externally with HTTPS. - -```yaml -apiVersion: route.openshift.io/v1 -kind: Route -metadata: - name: [app-name] - namespace: [namespace] - labels: - app: [app-name] -spec: - to: - kind: Service - name: [app-name] - weight: 100 - port: - targetPort: http - tls: - termination: edge - insecureEdgeTerminationPolicy: Redirect - wildcardPolicy: None -``` +Read `templates/route.yaml.template` and substitute `${APP_NAME}`, `${NAMESPACE}`. -**This Route will:** -- Expose app at: `https://[app-name]-[namespace].[cluster-domain]` -- Enable TLS with edge termination -- Redirect HTTP to HTTPS +Show the rendered YAML to user and confirm. **Proceed with creating this Route?** (yes/no/skip) ``` -**WAIT for user confirmation.** Do NOT create the Route until user explicitly responds. +**WAIT for user confirmation before proceeding.** - If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply - If user says "skip" → Skip Route creation and proceed to rollout monitoring @@ -364,28 +258,6 @@ oc delete all -l app=[app-name] -n [namespace] Your application is now live! ``` -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | Check existing deployments/services/routes | -| `resources_get` | Get resource details, route host | -| `resources_create_or_update` | Create Deployment, Service, Route | -| `pod_list` | Check pod status during rollout | -| `pod_logs` | Debug pod issues | -| `events_list` | Check events for errors | - -## Required Inputs - -| Input | Auto-detected | Must Confirm | -|-------|---------------|--------------| -| App name | Yes (from build) | Yes | -| Image | Yes (from ImageStream) | Yes | -| Port | Yes (from project files) | Yes | -| Replicas | Yes (default: 1) | Optional | -| Create Route | Yes (default: yes) | Yes | -| Namespace | Yes (from kubeconfig) | Yes | - ## Related Skills | Skill | Use When | diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index e34cd075..d0d165b9 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -21,12 +21,6 @@ Analyze the project to detect language/framework and recommend a build strategy. See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires user confirmation before proceeding. You MUST: -1. **Wait for user confirmation** on detected values before saving to session state -2. **Do NOT assume** detection is correct - always present findings and ask for confirmation -3. **Present options clearly** when multiple choices exist and wait for selection -4. **Never auto-select** deployment strategies or images without user approval - ## Workflow ### Step 1: Context Analysis @@ -40,8 +34,9 @@ If the user provided a Git URL (e.g., `https://github.com/...`): Use the **github-mcp-server** to analyze the repository directly without cloning: -1. Use GitHub MCP to list repository contents (look for indicator files) -2. Use GitHub MCP to read key files (`package.json`, `pom.xml`, `requirements.txt`, `Dockerfile`, etc.) +1. Use `mcp_github_get_file_contents(owner, repo, path="/")` to list repository contents +2. Read key files using `fetch_mcp_resource` with URI format: `repo://{owner}/{repo}/contents/{file-path}` + - Example: `repo://myorg/myrepo/contents/package.json` 3. Proceed with analysis as if local files ```markdown @@ -83,7 +78,7 @@ I couldn't access the repository directly. Options: **Which approach do you prefer?** ``` -**WAIT for user to select an option.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **Scenario C: No Context** If no files and no URL: @@ -237,7 +232,7 @@ Please confirm: Type 'yes' to confirm all with quick image selection, 'smart' for tailored recommendation, or tell me what to change. ``` -**WAIT for user confirmation.** Do NOT save configuration or proceed until user explicitly confirms or provides corrections. +**WAIT for user confirmation before proceeding.** - If user says "yes" → Save configuration with quick image selection - If user says "smart" → Invoke `/recommend-image` skill @@ -257,52 +252,8 @@ After successful detection, these values should be available for other skills: | `VERSION` | Language version | `20` | | `BUILDER_IMAGE` | Full S2I image reference | `registry.access.redhat.com/ubi9/nodejs-20` | | `BUILD_STRATEGY` | Build strategy | `Source` (S2I) or `Podman` | -| `DEPLOYMENT_TARGET` | Deployment target | `openshift` or `rhel` | -| `DEPLOYMENT_STRATEGY` | Deployment method | `S2I`, `Podman`, `Helm` (OpenShift) or `container`, `native` (RHEL) | +| `CONTAINER_PORT` | Application listen port | `8080` | | `HELM_CHART_PATH` | Path to Helm chart | `./chart` | -| `HELM_CHART_NAME` | Helm chart name | `my-app` | -| `HELM_CHART_VERSION` | Helm chart version | `0.1.0` | -| `HELM_CHART_DETECTED` | Whether Helm chart was found | `true` or `false` | -| `RHEL_HOST` | SSH target for RHEL deployment | `user@192.168.1.100` | -| `PYTHON_ENTRY_FILE` | Python entry point file (Python only) | `main.py` | -| `PYTHON_APP_MODULE` | APP_MODULE value for S2I (Python only) | `main:app` | -| `PYTHON_HAS_GUNICORN` | Whether gunicorn is in requirements (Python only) | `true` or `false` | - -## MCP Tools Used - -This skill uses: - -### github-mcp-server (for remote repositories) - -**IMPORTANT: GitHub MCP has two different patterns for browsing vs reading:** - -#### Browsing Repository Structure -Use `mcp_github_get_file_contents` to **list directories**: -``` -mcp_github_get_file_contents(owner="org", repo="repo", path="/") → root listing -mcp_github_get_file_contents(owner="org", repo="repo", path="src") → src/ contents -``` -Returns: JSON array with file metadata (name, path, sha, type, download_url) - -#### Reading File Contents -Use `fetch_mcp_resource` with GitHub resource URI to **read actual file content**: -``` -fetch_mcp_resource(server="github", uri="repo://owner/repo/contents/path/to/file") -``` -Returns: Actual file content as text - -**URI Format:** `repo://{owner}/{repo}/contents/{file-path}` - -**Examples:** -- `repo://RHEcosystemAppEng/sast-ai-frontend/contents/package.json` -- `repo://facebook/react/contents/README.md` -- `repo://myorg/myrepo/contents/src/index.ts` - -### Local file reading (for local projects) -- Standard file reading capabilities (`read_file` tool) - -### Terminal (fallback) -- `run_terminal_cmd` - Only if user selects "Clone & Inspect" for private repos ## Reference Documentation diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index b8b29bc9..af6f6d4c 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -22,14 +22,6 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** and wait for response -4. **Never auto-execute** chart creation, Helm installations, or upgrades - -If the user says "no" or wants modifications, address their concerns before proceeding. - ## Workflow ### Step 1: Check OpenShift Connection @@ -46,9 +38,7 @@ Use kubernetes MCP to verify cluster connection: Is this the correct cluster and namespace? (yes/no) ``` -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms. - -If user says "no", wait for them to switch context and tell you to continue. +**WAIT for user confirmation before proceeding.** ### Step 2: Detect Helm Chart @@ -136,10 +126,7 @@ I'll create a Helm chart based on your project. Proceed with creating the Helm chart? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the chart until user explicitly says "yes". - -- If user says "yes" → Create chart files -- If user says "no" → Ask what they would like to change or use a different approach +**WAIT for user confirmation before proceeding.** Use templates from templates/helm/ to generate: 1. Chart.yaml @@ -263,10 +250,7 @@ helm install [release-name] [chart-path] -n [namespace] [--set options] **Proceed with Helm deployment?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT execute the Helm install/upgrade until user explicitly says "yes". - -- If user says "yes" → Proceed with deployment -- If user says "no" → Ask what they would like to change +**WAIT for user confirmation before proceeding.** ### Step 7: Execute Deployment @@ -350,31 +334,6 @@ oc logs -l app.kubernetes.io/instance=[release-name] -n [namespace] -f Your application is live! ``` -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `helm_list` | Check existing releases | -| `helm_install` | Install new release | -| `helm_upgrade` | Upgrade existing release | -| `helm_status` | Get release status | -| `helm_history` | Get release history | -| `helm_rollback` | Rollback to revision | -| `helm_uninstall` | Remove release | -| `pods_list_in_namespace` | Monitor pod status | -| `pods_log` | View pod logs | -| `events_list` | Check for errors | - -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `RELEASE_NAME` | Helm release name | `my-app` | -| `CHART_PATH` | Path to chart | `./chart` | -| `CHART_VERSION` | Chart version | `0.1.0` | -| `RELEASE_REVISION` | Current revision | `1` | -| `ROUTE_HOST` | External URL | `my-app-ns.apps.cluster.com` | - ## Reference Documentation For detailed guidance, see: diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 104b6eae..06da3746 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -24,12 +24,6 @@ Provide intelligent, use-case-aware container image recommendations that go beyo See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires user input and confirmation. You MUST: -1. **Wait for user responses** to all questions before proceeding -2. **Do NOT assume** user preferences - always ask -3. **Present options clearly** and wait for selection -4. **Confirm final recommendation** before saving to session state - ## Workflow ### Step 1: Gather Context @@ -110,7 +104,7 @@ To recommend the optimal image, please tell me about your requirements: Please describe your use case or select from the options above. ``` -**WAIT for user to provide their requirements.** Do NOT proceed until user describes their use case or selects options. +**WAIT for user confirmation before proceeding.** ### Step 3: Evaluate Image Options @@ -156,7 +150,7 @@ After installing, run `/recommend-image` again for enhanced recommendations. - **install** - I'll install skopeo first ``` -**WAIT for user to select an option.** Do NOT proceed until user chooses. +**WAIT for user confirmation before proceeding.** If user continues without skopeo, proceed with static data and note: "Image metadata from static reference (not verified)". @@ -237,7 +231,7 @@ Based on your requirements: - Tell me if you have different requirements ``` -**WAIT for user to confirm or select an alternative.** Do NOT save configuration until user explicitly confirms. +**WAIT for user confirmation before proceeding.** ### Step 5: Handle Confirmation @@ -272,17 +266,6 @@ Return to Step 2 with new inputs. > **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). -## Output Variables - -After successful recommendation: - -| Variable | Description | Example | -|----------|-------------|---------| -| `BUILDER_IMAGE` | Full image reference | `registry.access.redhat.com/ubi9/nodejs-20-minimal` | -| `IMAGE_VARIANT` | Variant type | `minimal` | -| `SELECTION_RATIONALE` | Why this image | "Minimal variant for production security" | -| `ALTERNATIVES` | Fallback options | `["ubi9/nodejs-20", "ubi9/nodejs-22-minimal"]` | - ## Reference Documentation For detailed guidance, see: diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index 42f04dd9..470942c9 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -39,43 +39,13 @@ Deploy applications to standalone RHEL systems using Podman containers or native See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each phase. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next phase until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** SSH commands, file transfers, or service creation - -If the user says "no" or wants modifications, address their concerns before proceeding. - ## Workflow ### Phase 0: Introduction -```markdown -# Deploy to RHEL Host - -I'll help you deploy your application to a RHEL system. - -**What this workflow does:** -1. **Connect** - Establish SSH connection to your RHEL host -2. **Analyze** - Check target system capabilities (Podman, SELinux, firewall) -3. **Build** - Build container image or prepare native deployment -4. **Deploy** - Configure systemd service and networking -5. **Verify** - Ensure application is running and accessible - -**Deployment Strategies:** -- **Container (Podman)** - Run your app in a container managed by systemd -- **Native** - Install and run your app directly on the host - -**What I need from you:** -- SSH access to the target RHEL host (user@host) -- sudo privileges on the target host -- Your application source code - -**Ready to begin?** (yes/no) -``` +Present the workflow overview: Connect → Analyze → Strategy → Build/Deploy → Verify. Describe Container (Podman + systemd) vs Native (dnf + systemd) strategies. Ask: **Ready to begin?** (yes/no) -Wait for user confirmation before proceeding. +**WAIT for user confirmation before proceeding.** ### Phase 1: SSH Connection @@ -100,15 +70,11 @@ Example: `user@192.168.1.100` or `deploy@myserver.example.com` **Connection verification:** ```bash -# Test SSH connection ssh -o BatchMode=yes -o ConnectTimeout=10 [user]@[host] "echo 'Connection successful'" - -# If connection fails, provide troubleshooting: -# - Check host is reachable: ping [host] -# - Verify SSH key is configured -# - Check firewall allows SSH (port 22) ``` +If connection fails, troubleshoot: host reachability, SSH key configuration, firewall port 22. + Store `RHEL_HOST`, `RHEL_USER`, `RHEL_PORT` in session state. ### Phase 2: Target Host Analysis @@ -118,46 +84,26 @@ Store `RHEL_HOST`, `RHEL_USER`, `RHEL_PORT` in session state. Checking capabilities of [host]... -**System Information:** | Setting | Value | |---------|-------| | OS | [cat /etc/redhat-release] | | Kernel | [uname -r] | | Architecture | [uname -m] | - -**Container Runtime:** -| Setting | Status | -|---------|--------| | Podman | [Installed v4.x / Not installed] | -| Container Storage | [/var/lib/containers] | - -**System Services:** -| Setting | Status | -|---------|--------| | SELinux | [Enforcing / Permissive / Disabled] | | Firewall | [Active / Inactive] | -| systemd | Running | Is this the correct target host? (yes/no) ``` -**WAIT for user confirmation before proceeding.** Do NOT continue to Phase 3 until user confirms. - -If user says "no", ask what needs to be changed or allow them to specify a different host. +**WAIT for user confirmation before proceeding.** **Commands to gather information:** ```bash -# RHEL version ssh [target] "cat /etc/redhat-release" - -# Podman check ssh [target] "podman --version 2>/dev/null || echo 'Not installed'" - -# SELinux status ssh [target] "getenforce" - -# Firewall status ssh [target] "firewall-cmd --state 2>/dev/null || echo 'Not running'" ``` @@ -192,14 +138,6 @@ Append to Phase 2 output: These are informational warnings only — they do not block deployment. -**MCP tools used:** - -| Tool | Purpose | -|------|---------| -| `find_host_by_name` | Look up target system in Red Hat Insights | -| `get_system_cves` | Check CVEs on target system | -| `get_rhel_lifecycle` | Verify RHEL version support status | - ### Phase 3: Strategy Selection ```markdown @@ -219,7 +157,7 @@ Based on your project ([language]/[framework]) and target capabilities: 2. Native - Deploy directly on host ``` -**WAIT for user to select a strategy.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **If Podman not installed and user selects Container:** ```markdown @@ -232,7 +170,7 @@ sudo dnf install -y podman Proceed with Podman installation? (yes/no) ``` -**WAIT for user confirmation.** Only install Podman if user explicitly says "yes". +**WAIT for user confirmation before proceeding.** Store `DEPLOYMENT_STRATEGY` in session state. @@ -254,7 +192,7 @@ Store `DEPLOYMENT_STRATEGY` in session state. Which approach would you prefer? ``` -**WAIT for user to select an option.** Do NOT proceed until user makes a choice. +**WAIT for user confirmation before proceeding.** **For options 1 and 2 (building an image):** @@ -272,26 +210,14 @@ Use the `BUILDER_IMAGE` output from `/recommend-image` as the base image in the **For build on target:** ```bash -# Transfer source +# Transfer source and build rsync -avz --exclude node_modules --exclude .git ./ [target]:/tmp/[app-name]-build/ - -# If no Containerfile exists, create one with recommended base image -ssh [target] "test -f /tmp/[app-name]-build/Containerfile -o -f /tmp/[app-name]-build/Dockerfile" || \ -ssh [target] "cat > /tmp/[app-name]-build/Containerfile << 'EOF' -FROM [BUILDER_IMAGE] -# Containerfile generated using /recommend-image -WORKDIR /app -COPY . . -# Add language-specific build and run commands -EOF" - -# Build on target +# If no Containerfile exists, generate one using BUILDER_IMAGE from /recommend-image ssh [target] "cd /tmp/[app-name]-build && podman build -t [app-name]:latest ." ``` **For existing image:** ```bash -# Pull image on target ssh [target] "podman pull [image-reference]" ``` @@ -315,11 +241,7 @@ ssh [target] "podman pull [image-reference]" Proceed with this configuration? (yes/modify/cancel) ``` -**WAIT for user confirmation.** Do NOT proceed until user explicitly approves. - -- If user says "yes" → Continue to systemd unit creation -- If user says "modify" → Ask what they would like to change -- If user says "cancel" → Stop and preserve current state +**WAIT for user confirmation before proceeding.** ### Phase 4a-3: Systemd Unit Creation @@ -346,10 +268,7 @@ Creating systemd unit for Podman container. Proceed with creating this service? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the systemd unit until user explicitly says "yes". - -- If user says "yes" → Read the appropriate template, substitute variables, and create the service -- If user says "no" → Ask what they would like to change +**WAIT for user confirmation before proceeding.** **Steps to execute:** @@ -359,17 +278,9 @@ Proceed with creating this service? (yes/no) 4. Enable and start the service ```bash -# For rootful: -ssh [target] "sudo tee /etc/systemd/system/[app-name].service" < [generated-unit-file] -ssh [target] "sudo systemctl daemon-reload" -ssh [target] "sudo systemctl enable --now [app-name]" - -# For rootless: -ssh [target] "mkdir -p ~/.config/systemd/user" -ssh [target] "tee ~/.config/systemd/user/[app-name].service" < [generated-unit-file] -ssh [target] "systemctl --user daemon-reload" -ssh [target] "systemctl --user enable --now [app-name]" -ssh [target] "loginctl enable-linger [user]" # Keep user services running +# Rootful: transfer to /etc/systemd/system/, daemon-reload, enable --now +# Rootless: transfer to ~/.config/systemd/user/, daemon-reload, enable --now, enable-linger +ssh [target] "sudo systemctl daemon-reload && sudo systemctl enable --now [app-name]" ``` ### Phase 4a-4: Firewall Configuration @@ -394,10 +305,7 @@ sudo firewall-cmd --list-ports Proceed with firewall configuration? (yes/skip) ``` -**WAIT for user confirmation.** Do NOT modify firewall until user explicitly responds. - -- If user says "yes" → Configure firewall -- If user says "skip" → Skip firewall configuration and continue +**WAIT for user confirmation before proceeding.** --- @@ -420,7 +328,7 @@ ssh [target] "sudo dnf install -y [packages]" Proceed with installation? (yes/no) ``` -**WAIT for user confirmation.** Do NOT install packages until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** ### Phase 4b-2: Application Deployment @@ -437,21 +345,11 @@ Proceed with installation? (yes/no) 5. Configure SELinux context ```bash -# Create directory ssh [target] "sudo mkdir -p /opt/[app-name]" - -# Transfer files -rsync -avz --exclude node_modules --exclude .git --exclude __pycache__ \ - ./ [target]:/tmp/[app-name]-deploy/ +rsync -avz --exclude node_modules --exclude .git --exclude __pycache__ ./ [target]:/tmp/[app-name]-deploy/ ssh [target] "sudo cp -r /tmp/[app-name]-deploy/* /opt/[app-name]/" - -# Install dependencies (example for Node.js) -ssh [target] "cd /opt/[app-name] && npm install --production" - -# Set permissions +ssh [target] "cd /opt/[app-name] && npm install --production" # language-specific ssh [target] "sudo chown -R [service-user]:[service-user] /opt/[app-name]" - -# SELinux context ssh [target] "sudo semanage fcontext -a -t bin_t '/opt/[app-name](/.*)?'" ssh [target] "sudo restorecon -Rv /opt/[app-name]" ``` @@ -459,7 +357,7 @@ ssh [target] "sudo restorecon -Rv /opt/[app-name]" Proceed with deployment? (yes/no) ``` -**WAIT for user confirmation.** Do NOT transfer files or deploy until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** ### Phase 4b-3: Native Systemd Unit @@ -486,7 +384,7 @@ Proceed with deployment? (yes/no) Proceed with creating this service? (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the systemd unit until user explicitly says "yes". +**WAIT for user confirmation before proceeding.** **Steps to execute:** @@ -510,8 +408,6 @@ Same as container path - open required port with firewall-cmd. Your application is now running on [host]. ---- - **Application Summary:** | Setting | Value | |---------|-------| @@ -520,51 +416,17 @@ Your application is now running on [host]. | Strategy | [Container/Native] | | Service | [app-name].service | ---- - **Access URLs:** | Type | URL | |------|-----| | HTTP | http://[host]:[port] | | SSH | ssh [user]@[host] | ---- - -**Service Status:** -``` -[systemctl status output] -``` - ---- +**Service Status:** [systemctl status output] **Quick Commands:** -```bash -# View logs -sudo journalctl -u [app-name] -f - -# Restart service -sudo systemctl restart [app-name] - -# Stop service -sudo systemctl stop [app-name] - -# Check status -sudo systemctl status [app-name] - -# View container logs (if container deployment) -podman logs -f [app-name] - -# Remove deployment -sudo systemctl disable --now [app-name] -sudo rm /etc/systemd/system/[app-name].service -# For container: podman rm [app-name] -# For native: sudo rm -rf /opt/[app-name] -``` - ---- - -Your application is live! +Show quick commands for: view logs (journalctl), restart/stop/status (systemctl), container logs (if container), and removal steps. ``` ### Phase 5a: Handle Deployment Failure @@ -576,33 +438,19 @@ If the service fails to start or is not accessible: The service did not start successfully. -**Service Status:** -``` -[systemctl status output showing failure] -``` +**Service Status:** [systemctl status output showing failure] **Recent Errors:** | Time | Error | |------|-------| | [time] | [error from journalctl] | ---- - **Would you like me to diagnose the issue?** - -1. **Debug RHEL** (`/debug-rhel`) - Full system diagnosis - - Analyzes systemd status, journal logs, SELinux denials, firewall rules - - Identifies root cause and suggests remediation - -2. **Debug Container** (`/debug-container`) - If using container deployment - - Analyzes container state, logs, exit codes - -3. **View full logs** - Show complete journalctl output - +1. **Debug RHEL** (`/debug-rhel`) - Full system diagnosis (systemd, journal, SELinux, firewall) +2. **Debug Container** (`/debug-container`) - Container state, logs, exit codes +3. **View full logs** - Complete journalctl output 4. **Check SELinux** - Quick SELinux denial check - 5. **Check firewall** - Quick firewall port check - 6. **Stop and clean up** Select an option: @@ -614,19 +462,6 @@ Select an option: - If user selects "Debug Container" → Invoke `/debug-container` skill - After debugging → Offer to retry deployment -## Delegated Skills - -This skill delegates to other skills when needed: - -| Scenario | Delegated Skill | Purpose | -|----------|-----------------|---------| -| Building container image (no Containerfile) | `/recommend-image` | Get optimal UBI base image for the detected language/framework | - -When delegating to `/recommend-image`: -1. Provide detected `LANGUAGE`, `FRAMEWORK`, and `VERSION` from project analysis -2. Receive back: `BUILDER_IMAGE`, `IMAGE_VARIANT`, `SELECTION_RATIONALE` -3. Use `BUILDER_IMAGE` as the FROM image in generated Containerfile - ## Related Skills | Skill | Use When | @@ -634,10 +469,6 @@ When delegating to `/recommend-image`: | `/debug-rhel` | systemd failures, SELinux denials, firewall blocking, Insights CVE/advisor analysis | | `/debug-container` | Container startup issues on RHEL host | -## Optional MCP Servers - -- `lightspeed-mcp` - Red Hat Insights vulnerability and planning data (Phase 2b) - ## Reference Documentation For detailed guidance, see: diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index f671e26b..cf3a4e64 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -23,14 +23,6 @@ Before running this skill, ensure: See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. -**IMPORTANT:** This skill requires explicit user confirmation at each step. You MUST: -1. **Wait for user confirmation** before executing any actions -2. **Do NOT proceed** to the next step until the user explicitly approves -3. **Present options clearly** (yes/no/modify) and wait for response -4. **Never auto-execute** resource creation, builds, or deployments - -If the user says "no" or wants modifications, address their concerns before proceeding. - ## Workflow ### Step 1: Check OpenShift Connection @@ -49,9 +41,7 @@ Is this the correct cluster and namespace for the build? - no - Let me switch context ``` -**WAIT for user confirmation before proceeding.** Do NOT continue to Step 2 until user confirms. - -If user says "no", wait for them to switch context and tell you to continue. +**WAIT for user confirmation before proceeding.** ### Step 2: Gather Build Information @@ -97,9 +87,7 @@ Your application uses `[PYTHON_ENTRY_FILE]` as entry point, but `gunicorn` is no 3. **Continue anyway** - Proceed (build will likely fail) ``` -**WAIT for user to resolve the issue before proceeding.** - -**WAIT for user confirmation before proceeding.** Do NOT continue until user explicitly confirms these values or provides corrections. +**WAIT for user confirmation before proceeding.** **To detect Git URL:** - Read `.git/config` and extract `[remote "origin"]` url @@ -122,7 +110,7 @@ Namespace `[namespace]` does not exist. Would you like me to create it? (yes/no) ``` -**WAIT for user confirmation.** Only create the namespace if user explicitly says "yes". +**WAIT for user confirmation before proceeding.** If creating namespace, use `resources_create_or_update`: ```yaml @@ -158,11 +146,7 @@ spec: **Proceed with creating this ImageStream?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the ImageStream until user explicitly says "yes". - -- If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply -- If user says "no" → Ask what they would like to change -- If user wants modifications → Update the YAML and show again for confirmation +**WAIT for user confirmation before proceeding.** ### Step 5: Create BuildConfig @@ -269,11 +253,7 @@ spec: **Proceed with creating this BuildConfig?** (yes/no) ``` -**WAIT for user confirmation.** Do NOT create the BuildConfig until user explicitly says "yes". - -- If user says "yes" → Use kubernetes MCP `resources_create_or_update` to apply -- If user says "no" → Ask what they would like to change -- If user wants modifications → Update the YAML and show again for confirmation +**WAIT for user confirmation before proceeding.** ### Step 6: Start Build @@ -292,10 +272,7 @@ Resources created successfully! (You can also trigger builds later with: oc start-build [app-name]) ``` -**WAIT for user confirmation.** Do NOT start the build until user explicitly says "yes". - -- If user says "yes" → Create a Build resource as shown below -- If user says "no" → Complete this step and inform user how to start build manually later +**WAIT for user confirmation before proceeding.** If yes, create a Build resource: ```yaml @@ -394,44 +371,6 @@ What would you like to do? - If user selects "Debug Build" → Invoke `/debug-build` skill with build name - After debugging → Offer to retry build -## MCP Tools Used - -| Tool | Purpose | -|------|---------| -| `resources_list` | Check namespaces, existing ImageStreams/BuildConfigs | -| `resources_get` | Get specific resource details | -| `resources_create_or_update` | Create ImageStream, BuildConfig, Build | -| `pod_logs` | Stream build logs (builds run as pods) | -| `pod_list` | Find builder pod | -| `events_list` | Check for build events/errors | - -## Required Inputs - -| Input | Auto-detected | Must Confirm | -|-------|---------------|--------------| -| App name | Yes (from detect-project) | Yes | -| Git URL | Yes (from .git/config) | Yes | -| Git branch | Yes (default: main) | Optional | -| S2I image | Yes (from detect-project) | Yes | -| Namespace | Yes (from kubeconfig) | Yes | - -## Output - -On success, these values are available for `/deploy`: - -| Variable | Value | -|----------|-------| -| `IMAGE_REF` | `image-registry.openshift-image-registry.svc:5000/[ns]/[app]:latest` | -| `IMAGESTREAM_TAG` | `[app]:latest` | -| `BUILD_NAME` | `[app]-1` | - -## Related Skills - -| Skill | Use When | -|-------|----------| -| `/debug-build` | Build failures (source access, dependencies, registry issues) | -| `/deploy` | After successful build, to deploy the image | - ## Reference Documentation For detailed guidance, see: @@ -439,3 +378,7 @@ For detailed guidance, see: - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common build error patterns and troubleshooting - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc) + +**Related Skills:** +- `/debug-build` - Build failures (source access, dependencies, registry issues) +- `/deploy` - After successful build, to deploy the image diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index f358a402..474e365b 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -21,17 +21,6 @@ See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandat 2. Present results clearly and ask if user wants to proceed with fixes 3. Never auto-fix issues without user approval -## Trigger - -- User types `/validate-environment` -- User asks "check my environment", "what tools do I need", "am I ready to deploy" - -## Input Parameters - -| Parameter | Description | Default | -|-----------|-------------|---------| -| `TARGET` | What to validate: `all`, `openshift`, `rhel`, `containers` | `all` | - ## Execution Flow ### Step 1: Determine Validation Scope @@ -223,15 +212,6 @@ Options: --- -## Output Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `TOOLS_OK` | List of installed tools | `git,curl,oc,helm` | -| `TOOLS_MISSING` | List of missing tools | `skopeo` | -| `CLUSTER_CONNECTED` | OpenShift connectivity | `true` / `false` | -| `READY_FOR_SKILLS` | Skills that can run | `/deploy,/s2i-build` | - ## Reference Documentation For detailed guidance, see: From b0c32c491bbfde6c8ac3ac459da819de4b437271 Mon Sep 17 00:00:00 2001 From: ikrispin Date: Mon, 2 Mar 2026 20:08:36 +0200 Subject: [PATCH 4/4] add required skill sections for linter compliance --- .../skills/containerize-deploy/SKILL.md | 24 +++++++++++-------- rh-developer/skills/debug-build/SKILL.md | 21 ++++++++++------ rh-developer/skills/debug-container/SKILL.md | 17 +++++++++---- rh-developer/skills/debug-network/SKILL.md | 16 ++++++++++--- rh-developer/skills/debug-pipeline/SKILL.md | 16 ++++++++++--- rh-developer/skills/debug-pod/SKILL.md | 16 ++++++++++--- rh-developer/skills/debug-rhel/SKILL.md | 19 ++++++++++----- rh-developer/skills/deploy/SKILL.md | 20 +++++++++------- rh-developer/skills/detect-project/SKILL.md | 18 ++++++++++++-- rh-developer/skills/helm-deploy/SKILL.md | 18 ++++++++++++-- rh-developer/skills/recommend-image/SKILL.md | 11 +++++++-- rh-developer/skills/rhel-deploy/SKILL.md | 20 +++++++++------- rh-developer/skills/s2i-build/SKILL.md | 19 ++++++++++----- .../skills/validate-environment/SKILL.md | 20 +++++++++++++--- 14 files changed, 188 insertions(+), 67 deletions(-) diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index 1ef5d630..f3565dd9 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -19,6 +19,10 @@ Provide a complete, guided workflow from local source code to running applicatio └─→ [RHEL: /rhel-deploy] ──────────┘ ``` +## When to Use This Skill + +Use `/containerize-deploy` when a user wants a complete guided workflow from source code to running application on OpenShift or standalone RHEL systems. This skill orchestrates project detection, build strategy selection, and deployment with user confirmation at each phase. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -453,21 +457,21 @@ Present a summary including: - Quick commands: view logs, scale, rebuild, delete - Next steps: open app URL, set up webhooks, add env vars, configure autoscaling -## Related Skills +## Dependencies -| Skill | Use When | -|-------|----------| -| `/debug-pod` | Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) | -| `/debug-build` | S2I or Podman build failures | -| `/debug-network` | Service connectivity issues (no endpoints, 503 errors) | -| `/debug-rhel` | RHEL deployment failures (systemd, SELinux, firewall) | +### Required MCP Servers +- `openshift` - cluster resource management for OpenShift deployments -## Reference Documentation +### Related Skills +- `/debug-pod` - Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) +- `/debug-build` - S2I or Podman build failures +- `/debug-network` - Service connectivity issues (no endpoints, 503 errors) +- `/debug-rhel` - RHEL deployment failures (systemd, SELinux, firewall) -For detailed guidance, see: +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - Language detection, S2I builder images - [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection, LTS timelines - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python S2I configuration -- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL host deployment (when delegating to /rhel-deploy) +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL host deployment - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting - [docs/prerequisites.md](../../docs/prerequisites.md) - All required tools by skill diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index 6f6bd7f0..61801bc6 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -19,6 +19,10 @@ Before running this skill: 2. User has access to the target namespace 3. Build or BuildConfig name is known (or can be identified from recent builds) +## When to Use This Skill + +Use this skill when OpenShift builds fail, hang, or produce unexpected results. It diagnoses S2I builds, Docker/Podman builds, and BuildConfig issues by analyzing build pod logs, registry authentication, and source repository access. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -294,15 +298,18 @@ Select an option: For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for builds, BuildConfigs, and build pod logs -For detailed guidance, see: +### Related Skills +- `/s2i-build` - To retry build after fixing issues +- `/debug-pod` - To debug the builder pod directly +- `/deploy` - To deploy after a successful build + +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification - -**Related Skills:** -- `/s2i-build` - To retry build after fixing issues -- `/debug-pod` - To debug the builder pod directly -- `/detect-project` - To re-analyze project and builder image selection diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index 902601b4..71e48194 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -35,6 +35,10 @@ Diagnose local Podman/Docker container issues by automatically gathering contain See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +## When to Use This Skill + +Use `/debug-container` when local Podman or Docker containers fail to run, crash on startup, get OOM killed, or have image pull errors. This skill automates container inspection, log retrieval, image analysis, and resource constraint checking. + ## Workflow ### Step 1: Identify Target Container @@ -326,10 +330,15 @@ Select an option: For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](../../docs/debugging-patterns.md). -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `podman` - container inspection, logs, and image analysis + +### Related Skills +- `/debug-rhel` - systemd service issues on RHEL hosts +- `/recommend-image` - select a better base image -For detailed guidance, see: +### Reference Documentation - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns, exit codes - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (podman) -- `/debug-rhel` - For systemd service issues on RHEL hosts -- `/recommend-image` - To select a better base image diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index 1a2f4853..81656d80 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -19,6 +19,10 @@ Before running this skill: 2. User has access to the target namespace 3. Service, Route, or application name is known +## When to Use This Skill + +Use this skill when services cannot communicate, routes return 503/502 errors, or external access fails. It automates checking service endpoints, pod selector matching, route status, and network policy analysis to pinpoint connectivity issues. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -313,9 +317,15 @@ Select an option: For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md). -## Reference Documentation +## Dependencies -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for services, routes, endpoints, and network policies + +### Related Skills - `/debug-pod` - To debug specific backend pods - `/deploy` - To fix and redeploy the service + +### Reference Documentation +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index f2a60d76..571167f5 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -35,6 +35,10 @@ Tekton resources are standard Kubernetes CRDs. Use the generic MCP tools with th | TriggerTemplate | `TriggerTemplate` | `triggers.tekton.dev/v1beta1` | | TriggerBinding | `TriggerBinding` | `triggers.tekton.dev/v1beta1` | +## When to Use This Skill + +Use this skill when OpenShift Pipelines (Tekton) fail, hang, or produce unexpected results. It diagnoses PipelineRun failures, TaskRun step errors, workspace/PVC binding issues, and authentication problems by analyzing run status, step container logs, and related resources. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -286,11 +290,17 @@ Select an option: For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](../../docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). -## Reference Documentation +## Dependencies -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for PipelineRuns, TaskRuns, and Tekton CRDs + +### Related Skills - `/debug-pod` - To debug TaskRun pods directly - `/debug-build` - If the pipeline uses OpenShift Build tasks - `/debug-network` - If pipeline tasks fail due to network issues - `/validate-environment` - To verify OpenShift and pipeline operator setup + +### Reference Documentation +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index dd82ee62..9b1a9c1d 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -19,6 +19,10 @@ Before running this skill: 2. User has access to the target namespace 3. Pod or deployment name is known (or can be identified from recent deployments) +## When to Use This Skill + +Use this skill when pods are not running, restarting frequently, or stuck in non-ready states such as CrashLoopBackOff, ImagePullBackOff, OOMKilled, or Pending. It automates gathering pod status, events, logs, and resource constraints to identify the root cause. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -241,10 +245,16 @@ Select an option: For pod failure categories and exit code reference, see [debugging-patterns.md](../../docs/debugging-patterns.md). -## Reference Documentation +## Dependencies -- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees -- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for pod status, events, and logs + +### Related Skills - `/debug-build` - If pod failure is due to bad image from build - `/debug-network` - If pod is running but service connectivity fails - `/deploy` - To redeploy after fixing issues + +### Reference Documentation +- [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting trees +- [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index 0bb19be7..b0e23d86 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -39,6 +39,10 @@ See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandat This skill operates on **remote RHEL hosts** via SSH, not local MCP servers. Unlike OpenShift/Podman skills, direct Bash commands with SSH are the correct approach here since MCP servers run locally and cannot access remote systems. +## When to Use This Skill + +Use `/debug-rhel` when applications fail on standalone RHEL, Fedora, or CentOS hosts. This skill automates multi-step diagnosis of systemd service failures, SELinux denials, firewall blocking, and system resource problems via SSH. + ## Workflow ### Phase 1: SSH Connection @@ -435,14 +439,17 @@ Select an option: For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](../../docs/debugging-patterns.md) and [selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md). -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `lightspeed-mcp` (optional) - Red Hat Insights CVE and advisor checks in Phase 7 -For detailed guidance, see: +### Related Skills +- `/rhel-deploy` - redeploy after fixing issues +- `/debug-container` - debug Podman containers on the host + +### Reference Documentation - [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis - [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - RHEL deployment patterns - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools and setup - -**Related Skills:** -- `/rhel-deploy` - To redeploy after fixing issues -- `/debug-container` - To debug Podman containers on the host diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index 13a69e58..dfc93d53 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -19,6 +19,10 @@ Before running this skill: 2. Container image exists (from ImageStream or external registry) 3. Target namespace exists +## When to Use This Skill + +Use `/deploy` after building a container image (via `/s2i-build` or external registry) to create Deployment, Service, and Route resources on OpenShift. This skill handles port detection, replica configuration, rollout monitoring, and rollback on failure. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -258,16 +262,16 @@ oc delete all -l app=[app-name] -n [namespace] Your application is now live! ``` -## Related Skills +## Dependencies -| Skill | Use When | -|-------|----------| -| `/debug-pod` | Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) | -| `/debug-network` | Service connectivity issues (no endpoints, 503 errors) | -| `/debug-build` | Build failures before deployment | +### Required MCP Servers +- `openshift` - cluster resource creation and management -## Reference Documentation +### Related Skills +- `/debug-pod` - Pod failures (CrashLoopBackOff, OOMKilled, ImagePullBackOff) +- `/debug-network` - Service connectivity issues (no endpoints, 503 errors) +- `/debug-build` - Build failures before deployment -For detailed guidance, see: +### Reference Documentation - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc), cluster access verification - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index d0d165b9..7ddfa256 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -17,6 +17,12 @@ metadata: Analyze the project to detect language/framework and recommend a build strategy. This skill handles both local project directories and remote Git repositories. +## When to Use This Skill + +- User wants to containerize or deploy an application and needs language/framework detection +- User asks what tech stack a project uses or needs a build strategy recommendation +- Run before `/s2i-build`, `/recommend-image`, or `/rhel-deploy` to identify project type + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -255,9 +261,17 @@ After successful detection, these values should be available for other skills: | `CONTAINER_PORT` | Application listen port | `8080` | | `HELM_CHART_PATH` | Path to Helm chart | `./chart` | -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `github` - Remote repository analysis via GitHub API (for URL-based detection) + +### Related Skills +- `/s2i-build` - Build with the detected S2I builder image +- `/recommend-image` - Advanced image selection based on detection results +- `/rhel-deploy` - Deploy to RHEL using detected project info -For detailed guidance, see: +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (git) diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index af6f6d4c..2ebbde3e 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -18,6 +18,12 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or 2. Helm chart exists OR user wants to create one 3. Container image available (from registry or will be built) +## When to Use This Skill + +- User wants to deploy an application using Helm charts on OpenShift +- A Helm chart is detected in the project (Chart.yaml found) +- User invokes `/helm-deploy` or asks about Helm-based deployment + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -334,9 +340,17 @@ oc logs -l app.kubernetes.io/instance=[release-name] -n [namespace] -f Your application is live! ``` -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `openshift` - Helm install, upgrade, list, and uninstall operations + +### Related Skills +- `/deploy` - Alternative deployment without Helm charts +- `/debug-pod` - Troubleshoot pods after Helm deployment +- `/debug-network` - Diagnose networking issues with deployed services -For detailed guidance, see: +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - Container image references for chart values - [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Image variant selection for production deployments - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc, helm) diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 06da3746..deedc55c 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -266,9 +266,16 @@ Return to Step 2 with new inputs. > **See [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). -## Reference Documentation +## Dependencies -For detailed guidance, see: +### Required MCP Servers +- None required (uses Bash for skopeo image inspection) + +### Related Skills +- `/detect-project` - Provides language/framework detection input for recommendations +- `/s2i-build` - Build with the recommended image + +### Reference Documentation - [docs/image-selection-criteria.md](../../docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees - [docs/builder-images.md](../../docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability - [docs/dynamic-validation.md](../../docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index 470942c9..75237c99 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -35,6 +35,10 @@ Deploy applications to standalone RHEL systems using Podman containers or native 3. For container deployments: Podman installed on target 4. For native deployments: Required development tools available via dnf +## When to Use This Skill + +Use `/rhel-deploy` when deploying applications to standalone RHEL, Fedora, or CentOS systems via SSH. This skill handles Podman container or native dnf deployments with systemd service management, SELinux, and firewall configuration. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -462,17 +466,17 @@ Select an option: - If user selects "Debug Container" → Invoke `/debug-container` skill - After debugging → Offer to retry deployment -## Related Skills +## Dependencies -| Skill | Use When | -|-------|----------| -| `/debug-rhel` | systemd failures, SELinux denials, firewall blocking, Insights CVE/advisor analysis | -| `/debug-container` | Container startup issues on RHEL host | +### Required MCP Servers +- `lightspeed-mcp` (optional) - Red Hat Insights pre-deploy checks -## Reference Documentation +### Related Skills +- `/debug-rhel` - systemd failures, SELinux denials, firewall blocking +- `/debug-container` - Container startup issues on RHEL host -For detailed guidance, see: -- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - Comprehensive RHEL deployment reference: systemd unit templates, SELinux configuration, firewall commands, runtime package mapping +### Reference Documentation +- [docs/rhel-deployment.md](../../docs/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages - [docs/selinux-troubleshooting.md](../../docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common error patterns and troubleshooting - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (ssh, podman) diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index cf3a4e64..5e0b6efa 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -19,6 +19,10 @@ Before running this skill, ensure: 2. Target namespace/project exists or can be created 3. Git repository URL is available (or will use binary build) +## When to Use This Skill + +Use this skill after `/detect-project` to build container images from source code on OpenShift using Source-to-Image. It creates BuildConfig and ImageStream resources, triggers the build, and monitors progress with log streaming. + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -371,14 +375,17 @@ What would you like to do? - If user selects "Debug Build" → Invoke `/debug-build` skill with build name - After debugging → Offer to retry build -## Reference Documentation +## Dependencies + +### Required MCP Servers +- `openshift` - Kubernetes/OpenShift resource access for BuildConfigs, ImageStreams, and build monitoring -For detailed guidance, see: +### Related Skills +- `/debug-build` - Build failures (source access, dependencies, registry issues) +- `/deploy` - After successful build, to deploy the image + +### Reference Documentation - [docs/builder-images.md](../../docs/builder-images.md) - S2I builder image selection, version mapping - [docs/python-s2i-entrypoints.md](../../docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting - [docs/debugging-patterns.md](../../docs/debugging-patterns.md) - Common build error patterns and troubleshooting - [docs/prerequisites.md](../../docs/prerequisites.md) - Required tools (oc) - -**Related Skills:** -- `/debug-build` - Build failures (source access, dependencies, registry issues) -- `/deploy` - After successful build, to deploy the image diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index 474e365b..85cf8d8a 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -12,6 +12,12 @@ metadata: Check that required tools and environment are properly configured. +## When to Use This Skill + +- User wants to verify their environment before running deployment skills +- User encounters tool-related errors and needs a diagnostic check +- First-time setup or after environment changes to confirm readiness + ## Critical: Human-in-the-Loop Requirements See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandatory checkpoint behavior. @@ -21,7 +27,7 @@ See [Human-in-the-Loop Requirements](../../docs/human-in-the-loop.md) for mandat 2. Present results clearly and ask if user wants to proceed with fixes 3. Never auto-fix issues without user approval -## Execution Flow +## Workflow ### Step 1: Determine Validation Scope @@ -212,7 +218,15 @@ Options: --- -## Reference Documentation +## Dependencies + +### Required MCP Servers +- None required (uses Bash to check tool availability and cluster connectivity) + +### Related Skills +- `/containerize-deploy` - End-to-end deployment workflow (validate environment first) +- `/s2i-build` - S2I build requiring oc and cluster access +- `/deploy` - Deployment requiring oc and cluster access -For detailed guidance, see: +### Reference Documentation - [docs/prerequisites.md](../../docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification