Feedback on your kubectl-ai skill

[RichardHightower]

Noticed your kubectl-ai skill handles the intersection of CLI tooling and AI pretty elegantly—the way you've structured the disclosure makes it accessible without oversimplifying the complexity. Grabbed a B+ (86) and had some thoughts on the documentation flow if you're interested in feedback.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 86/100, solid B territory. This is based on Anthropic's best practices for skill design. Your writing style and examples are genuinely strong (9/10 and 3/3 respectively)—the prompt patterns in references are well-structured. Progressive Disclosure Architecture needs the most work (23/30)—mainly missing a table of contents and some structural consolidation that would improve token efficiency.

What's Working Well

• Writing is tight and instructional. You're using imperative mood throughout with zero marketing fluff. That's harder than it sounds.
• Examples are actually useful. The kubectl-ai commands paired with explanations in the prompt-patterns.md give people real starting points, not just theory.
• Clear metadata and triggers. Your description clearly signals "Phase IV AIOps, natural language commands, DevOps"—someone searching for Kubernetes + natural language will find this.
• Good layering. SKILL.md as the overview with references/prompt-patterns.md for templates is the right structure.

The Big One: Missing Table of Contents

Your SKILL.md is 254 lines without a TOC. That's the main thing pulling your PDA score down (23/30). When someone's scanning for "MCP Server Mode" or "Interactive Mode," they're scrolling blind.

Fix: Add a markdown TOC right after the frontmatter:

## Navigation
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage Patterns](#usage-patterns)
- [MCP Server Mode](#mcp-server-mode)
- [Interactive Mode](#interactive-mode)
- [Best Practices](#best-practices)

This alone gets you +3 points and makes the skill actually navigable. It's a 30-second change with real impact.

Other Things Worth Fixing

1. Add trigger phrases to your description. Right now it says "This skill should be used when..." but doesn't actually list the triggers. Rewrite to: "Performs kubectl ai operations. Use when asked to 'kubectl ai', 'run kubectl ai', or 'kubectl ai help'." Gets you +2 points on spec compliance.

2. MCP setup needs numbered steps. Your MCP Server Mode section shows code but lacks a workflow. Add: "1. Start kubectl-ai in MCP mode, 2. Update claude_desktop_config.json, 3. Restart Claude, 4. Verify connection." Makes it dramatically easier to follow (+2 points).

3. Consolidate platform-specific installs. You've got nearly identical curl/tar/chmod blocks for macOS ARM64, macOS AMD64, and Linux. Use a single block with a PLATFORM variable instead. Saves tokens, cleaner structure.

4. Add validation patterns to best practices. Mention explicit workflows: "1. Run kubectl-ai command, 2. Review generated kubectl command, 3. Approve/reject, 4. Verify with kubectl get." That's feedback loop territory (+1 point).

Quick Wins

• Add TOC to SKILL.md (+3 points) — Biggest bang for buck
• Add trigger phrases to description (+2 points) — Spec compliance win
• Number the MCP workflow (+2 points) — Ease of use improvement
• Consolidate install blocks — Token efficiency without point loss but better structure

---

Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.