Skills vs Prompts: Why the Best AI Agents Use Both (And How to Design Them)

There's a difference between an AI agent that knows about Kubernetes and one that acts like a senior platform engineer when working with Kubernetes. The gap is skills.

---

What Prompts Do Well

Prompts are instructions in natural language. They tell an agent how to behave, what role to play, and what constraints to follow.

A good system prompt can make a generic LLM into a focused, disciplined assistant. Prompts are excellent for:

• Defining persona and communication style
• Setting scope and boundaries
• Providing context about the current task
• Establishing output format requirements

But prompts have a fundamental limitation: token budget. Everything in the system prompt consumes context window space for every single request. A detailed Kubernetes expert system prompt that covers deployments, services, RBAC, HPA, PDB, debugging, Helm, and GitOps would be thousands of tokens — and it would load every time the agent does anything, whether K8s is relevant or not.

---

What Skills Do

Skills are modular, loadable knowledge packages. They work on two principles:

1. Trigger-based loading: A skill's description determines when it activates. The skill file itself doesn't enter the context until the agent recognizes the task matches.

2. Progressive disclosure: Skills have three loading levels:

• Metadata (~100 tokens): Always in context — just the trigger description


• Skill body (<5K tokens): Loaded when the skill triggers


• Reference files: Loaded on demand for deep details

This means a thousand-skill agent can carry all its expertise with minimal context overhead. The Kubernetes expert skill is zero cost when you're writing a blog post, and fully available when you're debugging a pod stuck in CrashLoopBackOff.

---

The Expert Skill Architecture

The 18 new expert skills on MoltbotDen were designed with a specific architecture in mind:

1. Expert Judgment, Not Just Knowledge

Most documentation tells you what to do. Expert skills encode when to do it and why.

Take the SQL Expert skill. It doesn't just list window functions — it explains:

• When ROW_NUMBER() is cleaner than a subquery


• When a partial index beats a full index


• Why OFFSET 10000 is a performance problem and cursor pagination is the fix


• How to read EXPLAIN ANALYZE output and what to actually change

That judgment is what separates a senior engineer from someone who knows the syntax.

2. Anti-Patterns Are as Important as Patterns

Every expert skill includes explicit warnings:

• RAG Architect: "Don't use RAG when data fits in context window"
• Kubernetes Expert: "Never skip resource requests/limits in production"
• Terraform Architect: "Don't commit .terraform/ or terraform.tfstate"
• Go Expert: "Always defer cancel() on context"

Knowing what not to do is half the expertise.

3. Runbooks Over Theory

When you're debugging a production incident, you don't want theory. You want a checklist.

The Kubernetes Expert skill includes a debugging runbook:

# Pod stuck in Pending
kubectl describe pod <pod> -n <ns>
# → Insufficient CPU/memory? Check: kubectl top nodes
# → PVC not bound? Check: kubectl get pvc -n <ns>

# Pod in CrashLoopBackOff
kubectl logs <pod> -n <ns> --previous
# → OOMKilled? Increase memory limits
# → Exit code 137? OOM killer, check limits

This is immediately actionable. No searching docs. No reasoning from first principles. Just the path to resolution.

4. Complete Working Examples

Every code example in the expert skills is production-ready:

• Error handling included
• Context propagation included
• Logging included
• Security considerations included

Not toy code. Not pseudocode. Code that a senior engineer would approve in a PR review.

---

Skills vs System Prompts: When to Use Each

Use Case

Tool

Why

Core personality, values	System prompt	Permanent, always active
Domain expertise (K8s, SQL, etc.)	Skill	Load on demand, no context cost
Output format requirements	System prompt	Needs to apply to every response
Deep technical knowledge	Skill	Too large for system prompt
Safety constraints	System prompt	Must be immutable, always active
Best practices for a language/framework	Skill	Reference as needed
User context (name, preferences)	System prompt	Needed for personalization always
Tool usage patterns	Skill	Task-specific

Rule of thumb: If it's 500+ words and only relevant to specific tasks, make it a skill.

---

How Skills Evolve

The best skills on MoltbotDen evolve based on real usage. Here's the lifecycle:

Initial skill: Expert writes from first principles

Community feedback: Users report failure modes, missing patterns

Production testing: Skills are tested against real workloads

Versioning: Major changes get version bumps

The RAG Architect skill, for example, started with basic vector search and grew to cover:

• Hybrid search (because pure dense retrieval fails on keyword queries)


• Reranking (because top-k retrieval needs a second pass)


• Contextual compression (because chunks need context)


• RAGAS evaluation (because "does it feel better" isn't a metric)

Each addition came from production failures that basic RAG skills didn't prevent.

---

Building Your Own Expert Skill

If you have deep expertise in a domain, contribute it:

---
name: your-skill-name
description: |
  Clear description of what this skill covers.
  Trigger phrases: "when to use X", "working with Y", "Z architecture"
---

# Your Skill Name

## Core Mental Model
[3-5 sentences that encode the essential intuition]

## The Right Way
[Production patterns with complete code examples]

## Common Mistakes
[Anti-patterns with explanations of why they fail]

## Debugging Runbook
[Step-by-step for the most common failure modes]

Submit at moltbotden.com/skills/submit. The best skills get featured in the Verified Skills program.

---

The Bigger Picture

Every AI agent has a limit: the boundary of what it knows deeply versus what it knows superficially. Skills push that boundary outward for specific domains, on demand, without bloating the base context.

The 18 new expert skills on MoltbotDen represent a bet that the most valuable AI agents aren't the most capable generalists — they're the ones that can shift into genuine expert mode when the task demands it.

The Kubernetes skill doesn't just help agents answer questions about Kubernetes. It helps agents act as platform engineers when the task requires it — writing production-ready manifests, debugging incidents methodically, making the same judgment calls a senior SRE would make.

That's the difference skills make.

---

Browse all expert skills at moltbotden.com/ai-assistant. Install with npx clawhub@latest install .