[dimetron]

Summary

Makes the kagent-tools image usable as a kagent 1.x Agent Plugin (OCI image source), bundling every CLI tool plus skills.

Image layout

• /opt/kagent-tools — full bundle: stdio MCP server (plugin.json + mcp.json), kubectl, helm, istioctl, kubectl-argo-rollouts, cilium, plugin kubeconfig, skills
• /opt/kagent-tools-skills — skills-only root, for use alongside the Helm-deployed server
• Legacy /tool-server and /bin/* preserved as symlinks (Helm chart unchanged)

Changes

• 7 skills in plugin/skills/ (k8s, helm, istio, argo rollouts, cilium, kubescape, prometheus)
• Env fallbacks: KAGENT_TOOLS_TOOLS, KAGENT_TOOLS_READ_ONLY, KAGENT_TOOLS_DEFAULT_KUBECONFIG; resolved kubeconfig exported to all CLIs
• Fix: stdio mode no longer writes trace output to stdout (would corrupt the MCP stream)
• Tests: cmd/plugin_bundle_test.go (manifests, frontmatter, every skill-referenced tool is registered), cmd/plugin_image_test.go (mirrors kagent validatePackage)
• make plugin-verify + plugin-verify CI job
• Docs: docs/kagent-skills.md, README, AGENTS.md; design + plan under docs/superpowers/

Known limitation

kagent's current 100 MiB per-package limit rejects the full root (~546 MiB). The skills-only root works on current kagent. The full root needs an upstream kagent change exempting platform-mounted OCI packages (Task 0 in the plan). The bundled MCP server is only started by the Go ADK harness.

Testing

• make test-only ✅, go vet ✅, golangci-lint v2.15.0 ✅ (pinned v2.13.2 can't load Go 1.27 export data — pre-existing)
• make plugin-verify ✅ (layout check + stdio tools/list smoke test)
• Validated against kagent's real materializer: skills-only root loads all 7 skills; full root resolves the stdio server correctly once the size limit is lifted
• Not yet tested on a live kagent cluster (exec / streaming logs via egress gateway)

Toolchain

• Go bumped to 1.27.3 (latest); golangci-lint pin v2.13.2 → v2.15.0 (v2.13.2 cannot load Go 1.27 export data)

[danielle-mustillo]

🤖 written by AI, but I extensively reviewed and vetted every suggestion/comment. 🤖

Thanks for putting this together. Shipping the skills inside the tools image is a nice way to keep skills and tool names in step. I checked it against current kagent and left some comments. Each one has a suggested change, and I applied all of them together on top of this branch to check them: go test -tags=test ./pkg/... ./internal/... ./cmd/..., make lint and make plugin-verify all pass.

The main point: kagent's plugin loader applies its 100 MiB package limit to mounted OCI images too (maxPackageBytes in go/core/pkg/agentplugins/materialize.go in kagent-dev/kagent). I ran that loader (agentplugins.Materialize, kagent main at d9cc3a82) against this branch's image, unpacked:

opt/kagent-tools:        REJECTED: validate mounted artifact: artifact exceeds 104857600 bytes
opt/kagent-tools-skills: ACCEPTED (k8s-troubleshooting/SKILL.md copied)

So the skills-only root, plus the tool server deployed by the Helm chart, is the path that works today. Most of the comments follow from that.

Also, could you drop docs/superpowers/? Those plan and spec files don't belong in the repo, and docs/kagent-skills.md already covers the user-facing content.

[dimetron]

Thanks for the thorough review, @danielle-mustillo. Every item is addressed in cc1e04e, and all threads are resolved.

Review items

#	Item	Fix
1	README wording	Uses your text: skills-only first, full root needs a future kagent release
2	Docs heading	Guide leads with skills-only; full root moved to its own section, with the 100 MiB limit
3–4	modelConfig	Both AgentTemplates set modelConfig
5	Tools list	Skills-only binding lists the 11 tools it needs (≤50 per binding, ≤128 per model request)
6	PROMETHEUS_URL not read	Now the default endpoint for all prometheus tools (+ test)
7	prometheus_promql_tool	Removed from the skill
8–9	Dockerfile layers	Plugin stage on wolfi-base; final stage has 3 layers ordered by change frequency: CLIs 504 MB, plugin 98 kB, server 69 MB
10–11	istio	Pod discovery step; response flag read from the istio-proxy access log
12	cilium node	Find the node first, then pass node_name; ids come from the list output
—	docs/superpowers	Removed

Same-class fixes found by sweeping the other skills

• argo: container_image: <container>=<image>, and the tool description is clarified
• kubescape: list manifests, then pass manifest_name (the tools have no severity filter)
• k8s: previous: true for logs from crashed containers

New guards, so these classes fail CI

• Each `arg: value` in a skill must be an input property of the tool named on that line.
• Skills may not reference LLM-backed tools.
• cmd/plugin_docs_test.go lints the guide's AgentTemplates: modelConfig, RemoteMCPServer with no apiGroup, ≤50 registered tools, a digest-pinned OCI ref, and the tools list covers what the skills use.

Follow-ups (pre-existing issues, out of scope here): #92 chart env vars nothing reads · #93 LLM-backed tools registered without an LLM · #94 LOG_LEVEL · #95 CLI checksum verification · #96 Grafana provider via gcx

[danielle-mustillo]

Thanks, every review item is fixed. I filed #97 as a follow-up, not a blocker: publish the skills-only root as its own small image, so an Agent that mounts it doesn't pull the whole tools image.