A hands-on walkthrough of building a read-only Kubernetes debugging AI agent for VictoriaMetrics using Claude Code. The guide covers creating a Claude Code Marketplace and Plugin structure in a GitHub repo, defining an agent (k8s-pod-debugger) with YAML frontmatter, system prompt, and least-privilege tool permissions, and writing a reusable SKILL.md for environment-specific query templates (MetricsQL, LogsQL, Alertmanager). The post explains why Skills were chosen over MCP for this use case, details the full agent file with allowed/denied kubectl and curl commands, and includes a cross-platform bootstrap script for setting up required environment variables.
Table of contents
ContentsOverall Structure and planMCP vs Skills: why skillsCreating the MarketplaceMarketplace: the .claude-plugin/marketplace.json filePlugin: the plugins/k8s-tools/.claude-plugin/plugin.json fileThe .claude/settings.json fileThe .gitignore fileCreating the AI AgentThe plugins/k8s-tools/agents/k8s-pod-debugger.md fileFrontmatter: Name and Description fieldsFrontmatter: Permissions and Tools fieldsGet Arseny Zinchenko (setevoy) ’s stories in your inboxBody: the Agent’s System PromptThe full k8s-pod-debugger.md fileSkill: k8s-troubleshooting-flowWhy a Skill, separate from the System Prompt?The plugins/k8s-tools/skills/k8s-troubleshooting-flow/SKILL.md fileCreating the Bootstrap scriptVerifying the Marketplace and PluginThe CLAUDE.md fileThe README.md fileVerifying extraKnownMarketplacesSort: