feat: ship the kagent-tools skills with a k8s-agent, and add skills to the agent template form

.github/workflows/ci.yaml

@@ -176,6 +176,10 @@ jobs:
             replicas: 0
           kagent-tools:
             enabled: false
+          # The lifecycle suite applies its own Harness named kagent.
+          builtins:
+            harness:
+              enabled: false
           substrateWorkerPool:
             create: true
             replicas: 4

Makefile

@@ -449,6 +449,11 @@ helm-version: helm-cleanup
 	helm package -d "$(HELM_DIST_FOLDER)" "$(HELM_SOURCE_DIR)/kagent-crds"
 	helm package -d "$(HELM_DIST_FOLDER)" "$(HELM_SOURCE_DIR)/kagent"
 
+.PHONY: builtin-skills-catalog
+builtin-skills-catalog: ## Regenerate the built-in skills catalog from the kagent-tools image
+	bash scripts/builtin-skills-catalog.sh > "$(HELM_SOURCE_DIR)/kagent/files/builtin-skills.json.tmp"
+	mv "$(HELM_SOURCE_DIR)/kagent/files/builtin-skills.json.tmp" "$(HELM_SOURCE_DIR)/kagent/files/builtin-skills.json"
+
 .PHONY: helm-dev
 helm-dev: ## Prepare development charts with the images published by local builds
 	@test -d "$(RUNTIME_BUILD_METADATA_DIR)" || { echo "Missing runtime image metadata. Run make build before preparing development charts." >&2; exit 1; }

helm/kagent/Chart-template.yaml

@@ -7,7 +7,7 @@ annotations:
   "org.opencontainers.image.source": "https://github.com/kagent-dev/kagent"
 dependencies:
   - name: kagent-tools
-    version: 0.3.0
+    version: 0.3.1
     repository: oci://ghcr.io/kagent-dev/tools/helm
     condition: kagent-tools.enabled
   - name: oauth2-proxy

helm/kagent/files/builtin-skills.json

@@ -0,0 +1,35 @@
+{
+  "image": "ghcr.io/kagent-dev/kagent/tools@sha256:607cb0ac95c9905529ad1cfebeff3aa2fbf68aa81861ed3bbba9d71a7477d640",
+  "skills": [
+    {
+      "name": "argo-rollouts-progressive-delivery",
+      "description": "Operate Argo Rollouts canary and blue-green releases (status, promote, pause, change image) with the kagent-tools argo_* MCP tools. Use when a Rollout is progressing, paused, degraded, or needs a new image.",
+      "path": "opt/kagent-tools-skills/skills/argo-rollouts-progressive-delivery"
+    },
+    {
+      "name": "helm-release-management",
+      "description": "Inspect, upgrade, roll forward and uninstall Helm releases with the kagent-tools helm_* MCP tools. Use for questions about installed charts, release status, values, failed upgrades, or adding chart repositories.",
+      "path": "opt/kagent-tools-skills/skills/helm-release-management"
+    },
+    {
+      "name": "istio-traffic-debugging",
+      "description": "Debug Istio service-mesh traffic (503s, mTLS failures, routing not applied, sidecar or ambient/waypoint issues) using the kagent-tools istio_* MCP tools. Use when requests between mesh services fail or routing rules do not take effect.",
+      "path": "opt/kagent-tools-skills/skills/istio-traffic-debugging"
+    },
+    {
+      "name": "k8s-troubleshooting",
+      "description": "Diagnose unhealthy Kubernetes workloads (CrashLoopBackOff, Pending, ImagePullBackOff, OOMKilled, failing readiness, unreachable Services) using the kagent-tools k8s_* MCP tools. Use when a pod, deployment or service is not working as expected.",
+      "path": "opt/kagent-tools-skills/skills/k8s-troubleshooting"
+    },
+    {
+      "name": "kubescape-security-posture",
+      "description": "Review cluster security posture with Kubescape results (configuration scans, image vulnerabilities, application profiles, network neighborhoods) using the kagent-tools kubescape_* MCP tools. Use for security reviews, CVE questions, or hardening recommendations.",
+      "path": "opt/kagent-tools-skills/skills/kubescape-security-posture"
+    },
+    {
+      "name": "prometheus-observability",
+      "description": "Answer questions about cluster and application metrics (error rates, latency, saturation, scrape health) with the kagent-tools prometheus_* MCP tools. Use when investigating performance, alerts, or whether a target is scraped. Requires PROMETHEUS_URL to be configured.",
+      "path": "opt/kagent-tools-skills/skills/prometheus-observability"
+    }
+  ]
+}

helm/kagent/templates/_helpers.tpl

@@ -13,6 +13,38 @@
 {{- $images | mustToJson -}}
 {{- end -}}
 
+{{/*
+The built-in skills catalog as JSON. builtins.skills.image and builtins.skills.list
+replace the packaged catalog. Empty when turned off.
+*/}}
+{{- define "kagent.builtinSkillsCatalog" -}}
+{{- if and (dig "builtins" "enabled" false .Values.AsMap) (dig "builtins" "skills" "enabled" false .Values.AsMap) -}}
+  {{- $catalog := .Files.Get "files/builtin-skills.json" | mustFromJson -}}
+  {{- with .Values.builtins.skills.image -}}
+    {{- $catalog = dict "image" . "skills" ($.Values.builtins.skills.list | default (list)) -}}
+  {{- end -}}
+  {{- if not (regexMatch "^[^[:space:]@]+@sha256:[0-9a-f]{64}$" $catalog.image) -}}
+    {{- fail (printf "builtins.skills.image must be pinned by sha256 digest: %q" $catalog.image) -}}
+  {{- end -}}
+  {{- range $catalog.skills -}}
+    {{- if not (and .name .path) -}}
+      {{- fail (printf "builtins.skills.list: each skill needs a name and a path, got %s" (mustToJson .)) -}}
+    {{- end -}}
+  {{- end -}}
+  {{/* The Prometheus skill needs a tool server URL it accepts (http:// or https://). */}}
+  {{- $prometheusURL := dig "kagent-tools" "tools" "prometheus" "url" "" .Values.AsMap -}}
+  {{- if not (regexMatch "^https?://" $prometheusURL) -}}
+    {{- $skills := list -}}
+    {{- range $catalog.skills -}}
+      {{- if ne .name "prometheus-observability" -}}{{- $skills = append $skills . -}}{{- end -}}
+    {{- end -}}
+    {{- $_ := set $catalog "skills" $skills -}}
+  {{- end -}}
+  {{- $_ := set $catalog "image" (include "kagent.mirroredImage" (dict "root" $ "image" $catalog.image)) -}}
+  {{- $catalog | mustToJson -}}
+{{- end -}}
+{{- end -}}
+
 {{/*
 Create a default fully qualified app name.
 */}}

helm/kagent/templates/builtin-agents.yaml

@@ -0,0 +1,229 @@
+{{- $catalog := include "kagent.builtinSkillsCatalog" . | default "{}" | mustFromJson }}
+{{- $byName := dict }}
+{{- range $catalog.skills | default (list) }}
+{{- $_ := set $byName .name . }}
+{{- end }}
+{{- $toolServer := printf "%s-tool-server" (include "kagent.fullname" .) }}
+{{- /* Both agents need the built-in Harness, the worker pool, kagent-tools and the k8s-troubleshooting skill. */}}
+{{- $ready := and (dig "builtins" "enabled" false .Values.AsMap) (dig "builtins" "harness" "enabled" false .Values.AsMap) .Values.substrateWorkerPool.create (index .Values "kagent-tools" "enabled") (hasKey $byName "k8s-troubleshooting") }}
+{{- if and $ready (dig "builtins" "k8sAgent" "enabled" false .Values.AsMap) }}
+{{- $skill := get $byName "k8s-troubleshooting" }}
+apiVersion: api.kagent.dev/v1alpha3
+kind: AgentTemplate
+metadata:
+  name: {{ .Values.builtins.k8sAgent.name | quote }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+spec:
+  description: "Kubernetes assistant: finds and fixes problems with workloads in the cluster where kagent runs."
+  modelConfig:
+    name: {{ include "kagent.defaultModelConfigName" . }}
+  promptTemplate:
+    dataSources:
+      - name: kagent-builtin-prompts
+        alias: builtin
+  systemPrompt: |
+    You help users run and troubleshoot workloads in the Kubernetes cluster
+    where kagent runs. When a question matches one of your skills, load that
+    skill and follow it.
+
+    {{`{{include "builtin/skills-usage"}}`}}
+
+    {{`{{include "builtin/kubernetes-context"}}`}}
+
+    {{`{{include "builtin/tool-usage-best-practices"}}`}}
+
+    {{`{{include "builtin/safety-guardrails"}}`}}
+  tools:
+    - mcp:
+        server:
+          kind: RemoteMCPServer
+          name: {{ $toolServer }}
+        tools:
+          - k8s_describe_resource
+          - k8s_generate_resource
+          - k8s_get_available_api_resources
+          - k8s_get_cluster_configuration
+          - k8s_get_events
+          - k8s_get_pod_logs
+          - k8s_get_resource_yaml
+          - k8s_get_resources
+          - k8s_wait
+    # These tools change the cluster, so each call waits for the user's approval.
+    - mcp:
+        server:
+          kind: RemoteMCPServer
+          name: {{ $toolServer }}
+        requireApproval: true
+        tools:
+          - k8s_annotate_resource
+          - k8s_apply_manifest
+          - k8s_check_service_connectivity
+          - k8s_create_resource
+          - k8s_create_resource_from_url
+          - k8s_delete_resource
+          - k8s_execute_command
+          - k8s_label_resource
+          - k8s_patch_resource
+          - k8s_patch_status
+          - k8s_remove_annotation
+          - k8s_remove_label
+          - k8s_rollout
+          - k8s_scale
+  skills:
+    - name: {{ $skill.name | quote }}
+      source:
+        oci: {{ $catalog.image | quote }}
+        path: {{ $skill.path | quote }}
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Agent
+metadata:
+  name: {{ .Values.builtins.k8sAgent.name | quote }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+spec:
+  harnessRef:
+    name: {{ .Values.builtins.harness.name | quote }}
+  template:
+    ref:
+      name: {{ .Values.builtins.k8sAgent.name | quote }}
+{{- end }}
+{{- if and $ready (dig "builtins" "platformAgent" "enabled" false .Values.AsMap) }}
+{{- /* The Helm, Istio and Argo skills and their tools are added when the catalog has them. */}}
+{{- $helm := hasKey $byName "helm-release-management" }}
+{{- $istio := hasKey $byName "istio-traffic-debugging" }}
+{{- $argo := hasKey $byName "argo-rollouts-progressive-delivery" }}
+{{- $topics := list "workloads" }}
+{{- if $helm }}{{ $topics = append $topics "Helm releases" }}{{ end }}
+{{- if $istio }}{{ $topics = append $topics "Istio traffic" }}{{ end }}
+{{- if $argo }}{{ $topics = append $topics "Argo Rollouts" }}{{ end }}
+{{- $covers := $topics | first }}
+{{- if gt (len $topics) 1 }}{{ $covers = printf "%s and %s" (initial $topics | join ", ") (last $topics) }}{{ end }}
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: AgentTemplate
+metadata:
+  name: {{ .Values.builtins.platformAgent.name | quote }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+spec:
+  description: {{ printf "Platform assistant: runs and troubleshoots %s in the cluster where kagent runs." $covers | quote }}
+  modelConfig:
+    name: {{ include "kagent.defaultModelConfigName" . }}
+  promptTemplate:
+    dataSources:
+      - name: kagent-builtin-prompts
+        alias: builtin
+  systemPrompt: |
+    You help users run and troubleshoot {{ $covers }}
+    in the Kubernetes cluster where kagent runs. When a question matches one
+    of your skills, load that skill and follow it.
+
+    {{`{{include "builtin/skills-usage"}}`}}
+
+    {{`{{include "builtin/kubernetes-context"}}`}}
+
+    {{`{{include "builtin/tool-usage-best-practices"}}`}}
+
+    {{`{{include "builtin/safety-guardrails"}}`}}
+  tools:
+    - mcp:
+        server:
+          kind: RemoteMCPServer
+          name: {{ $toolServer }}
+        tools:
+          - k8s_describe_resource
+          - k8s_generate_resource
+          - k8s_get_available_api_resources
+          - k8s_get_cluster_configuration
+          - k8s_get_events
+          - k8s_get_pod_logs
+          - k8s_get_resource_yaml
+          - k8s_get_resources
+          - k8s_wait
+          {{- if $helm }}
+          - helm_get_release
+          - helm_list_releases
+          {{- end }}
+          {{- if $istio }}
+          - istio_analyze_cluster_configuration
+          - istio_generate_waypoint
+          - istio_list_waypoints
+          - istio_proxy_config
+          - istio_proxy_status
+          - istio_version
+          - istio_waypoint_status
+          - istio_ztunnel_config
+          {{- end }}
+          {{- if $argo }}
+          - argo_check_plugin_logs
+          - argo_rollouts_list
+          - argo_verify_argo_rollouts_controller_install
+          - argo_verify_kubectl_plugin_install
+          {{- end }}
+    # These tools change the cluster or the tool server, so each call waits for the user's approval.
+    # argo_verify_gateway_plugin installs the Gateway API plugin when it is missing.
+    - mcp:
+        server:
+          kind: RemoteMCPServer
+          name: {{ $toolServer }}
+        requireApproval: true
+        tools:
+          - k8s_annotate_resource
+          - k8s_apply_manifest
+          - k8s_check_service_connectivity
+          - k8s_create_resource
+          - k8s_create_resource_from_url
+          - k8s_delete_resource
+          - k8s_execute_command
+          - k8s_label_resource
+          - k8s_patch_resource
+          - k8s_patch_status
+          - k8s_remove_annotation
+          - k8s_remove_label
+          - k8s_rollout
+          - k8s_scale
+          {{- if $helm }}
+          - helm_repo_add
+          - helm_repo_update
+          - helm_uninstall
+          - helm_upgrade
+          {{- end }}
+          {{- if $istio }}
+          - istio_apply_waypoint
+          - istio_delete_waypoint
+          {{- end }}
+          {{- if $argo }}
+          - argo_pause_rollout
+          - argo_promote_rollout
+          - argo_set_rollout_image
+          - argo_verify_gateway_plugin
+          {{- end }}
+  skills:
+    {{- range $name := list "k8s-troubleshooting" "helm-release-management" "istio-traffic-debugging" "argo-rollouts-progressive-delivery" }}
+    {{- with get $byName $name }}
+    - name: {{ .name | quote }}
+      source:
+        oci: {{ $catalog.image | quote }}
+        path: {{ .path | quote }}
+    {{- end }}
+    {{- end }}
+---
+apiVersion: api.kagent.dev/v1alpha3
+kind: Agent
+metadata:
+  name: {{ .Values.builtins.platformAgent.name | quote }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+spec:
+  harnessRef:
+    name: {{ .Values.builtins.harness.name | quote }}
+  template:
+    ref:
+      name: {{ .Values.builtins.platformAgent.name | quote }}
+{{- end }}

helm/kagent/templates/builtin-harness.yaml

@@ -0,0 +1,19 @@
+{{- if and (dig "builtins" "enabled" false .Values.AsMap) (dig "builtins" "harness" "enabled" false .Values.AsMap) .Values.substrateWorkerPool.create }}
+{{- if not .Values.builtins.harness.snapshotLocation }}
+{{- fail "builtins.harness.snapshotLocation is required: set the snapshot storage location for the default Harness" }}
+{{- end }}
+apiVersion: api.kagent.dev/v1alpha3
+kind: Harness
+metadata:
+  name: {{ .Values.builtins.harness.name | quote }}
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+spec:
+  kagent: {}
+  substrate:
+    workerPoolRef:
+      name: {{ .Values.substrateWorkerPool.name | quote }}
+    snapshotPolicy:
+      location: {{ .Values.builtins.harness.snapshotLocation | quote }}
+{{- end }}

helm/kagent/templates/ui-configmap.yaml

@@ -19,3 +19,6 @@ data:
   {{- if .Values.ui.streamTimeoutSeconds }}
   KAGENT_UI_STREAM_TIMEOUT_MS: {{ mul (int .Values.ui.streamTimeoutSeconds) 1000 | quote }}
   {{- end }}
+  {{- with include "kagent.builtinSkillsCatalog" . }}
+  KAGENT_UI_BUILTIN_SKILLS: {{ . | quote }}
+  {{- end }}