Skip to content

feat: ship kagent 1.x skills bundle in the tools OCI image - #91

Open
dimetron wants to merge 3 commits into
mainfrom
feat/kagent-skills-bundle
Open

dimetron wants to merge 3 commits into
mainfrom
feat/kagent-skills-bundle

Conversation

@dimetron

@dimetron dimetron commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

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)

Make the kagent-tools image usable as a kagent 1.x Agent Plugin source:

- /opt/kagent-tools: full bundle (stdio MCP server, kubectl, helm,
  istioctl, kubectl-argo-rollouts, cilium, kubeconfig, skills)
- /opt/kagent-tools-skills: skills-only root for use with the
  Helm-deployed server
- seven SKILL.md skills, one per tool provider
- legacy /tool-server and /bin/* paths preserved as symlinks
- env fallbacks (KAGENT_TOOLS_TOOLS, KAGENT_TOOLS_READ_ONLY,
  KAGENT_TOOLS_DEFAULT_KUBECONFIG); kubeconfig exported to all CLIs
- stdio mode keeps stdout clean (trace exporter writes to stderr)
- plugin bundle/image tests, make plugin-verify, CI job, docs

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Dmytro Rashko <dimetron@me.com>
@dimetron
dimetron requested a review from EItanya as a code owner October 24, 2026 23:46
dimetron and others added 2 commits October 25, 2026 02:19
golangci-lint v2.13.2 cannot load Go 1.27 export data, so the lint pin
moves with the toolchain.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Dmytro Rashko <dimetron@me.com>
- track plugin/mcp.json (a global **/mcp.json ignore had dropped it)
- docs: omit apiGroup on RemoteMCPServer refs (kagent CEL rejects it)
- share logger.UseStderrEnv/UseStderr instead of repeated literals
- move env export out of run() into tested applyServerEnvironment,
  propagating Setenv errors
- generic decodeStrict without any; KUBECONFIG constant
- image test: resolve root symlinks, assert /usr/bin legacy links
- verify script runs /tool-server, /bin/kubectl and /bin/helm

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Dmytro Rashko <dimetron@me.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant