Agent Skills Basics

This section shows how to scope and run packaged SME skills for container and Kubernetes work - Dockerfile review, manifest lint, and incident triage - as reusable automations.

Prerequisites

• Docker Engine 29.6.1 with BuildKit as the default builder (docker buildx version).
• kubectl matched to your cluster minor (Kubernetes 1.36.2; keep the client within one minor of the API server).
• A YAML linter and validator: kube-linter and kubeconform for static manifest checks.
• An image scanner: Trivy or Grype for CVE and misconfiguration findings.
• Quick install on Debian/Ubuntu CI runners:

# kubeconform: schema validation against the target K8s version
curl -sL https://github.com/yannh/kubeconform/releases/latest/download/kubeconform-linux-amd64.tar.gz | tar xz
sudo mv kubeconform /usr/local/bin/

Basic Examples

1. Define a skill's scope in one sentence

State exactly what the skill reviews and what it ignores so it stays maintainable.

Dockerfile Review Skill: checks build cache order, base image pinning,
non-root USER, and secret leakage in the final image. It does NOT
review application code or Kubernetes manifests.

• A one-sentence scope keeps criteria focused and reviews fast.
• Explicitly naming what is out of scope prevents the skill from sprawling.
• Each review surface (Dockerfile, manifest, incident) gets its own skill.
• Narrow scope makes version pinning and ownership tractable.

2. Pin the skill to a Kubernetes minor

Record the target minor so schema checks match the cluster.

kubeconform -kubernetes-version 1.36.2 -strict -summary deploy/

• -kubernetes-version validates manifests against that minor's schemas.
• -strict rejects unknown fields, catching typos like limts.
• Pinning prevents passing manifests that use removed or renamed APIs.
• Bump the pin deliberately when clusters upgrade, then re-review criteria.

3. Lint a Dockerfile for the common failures

Run a static pass before any human reads the file.

# flagged: unpinned base tag and no non-root user
FROM node:22
COPY . .
RUN npm ci
CMD ["node", "server.js"]

• The node:22 tag is mutable; pin to a digest or patch tag for reproducibility.
• No USER line means the container runs as root, which Pod Security rejects.
• Copying the whole context before npm ci busts the dependency cache on every source change.
• The skill returns each finding with a rationale and a corrected snippet.

4. Lint a manifest for missing safety fields

Catch absent probes and limits before the Deployment merges.

kube-linter lint deploy/ --include no-read-only-root-fs,unset-cpu-requirements

• kube-linter ships built-in checks for probes, limits, and root filesystems.
• Missing resource requests break the scheduler's bin-packing and let pods starve neighbors.
• Missing probes leave Kubernetes unable to detect a hung or not-yet-ready container.
• Findings map directly to the manifest fields that need adding.

5. Scan the built image for CVEs

Fail the build on fixable high-severity vulnerabilities.

trivy image --severity HIGH,CRITICAL --exit-code 1 myapp:1.4.2

• --exit-code 1 turns findings into a failing CI step.
• Filtering to HIGH and CRITICAL keeps the gate actionable rather than noisy.
• Scan the final image tag, not the builder stage, to reflect what ships.
• Pair with a base-image bump when a fixed version exists upstream.

6. Read a pod's real status for triage

Start every incident from kubectl get and describe, never from guesses.

kubectl get pod api-7d9f -o wide
kubectl describe pod api-7d9f

• The STATUS column names the state: CrashLoopBackOff, ImagePullBackOff, Pending.
• describe shows the container reason, last exit code, and recent events.
• Events reveal scheduling, image pull, and probe failures in plain text.
• A triage skill branches on exactly these two outputs.

7. Validate before you apply

Use a server-side dry run to catch admission and schema errors.

kubectl apply -f deploy/ --dry-run=server

• --dry-run=server runs admission webhooks and validation without persisting.
• It catches Pod Security violations that static linters miss.
• This is the last gate before a manifest reaches the cluster.
• Wire it into CI so no manifest merges without passing admission.

Intermediate Examples

8. Chain skills in a CI pipeline

Run review, lint, scan, and dry-run as ordered gates.

steps:
  - run: hadolint Dockerfile
  - run: docker buildx build -t myapp:$SHA .
  - run: trivy image --severity HIGH,CRITICAL --exit-code 1 myapp:$SHA
  - run: kubeconform -kubernetes-version 1.36.2 -strict deploy/
  - run: kube-linter lint deploy/

• Ordering matters: lint the Dockerfile before building, scan after building.
• Each step is a distinct skill with its own criteria and exit behavior.
• The pipeline encodes the standard so every service passes the same bar.
• Non-blocking findings can warn instead of failing early stages.

9. Enforce Pod Security Standards at the namespace

Let the cluster reject non-compliant pods so the skill and the platform agree.

apiVersion: v1
kind: Namespace
metadata:
  name: payments
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: v1.36

• The restricted level forbids running as root and requires dropped capabilities.
• enforce-version pins the policy to a Kubernetes minor, matching your skill's pin.
• The manifest skill should check the same rules the namespace enforces.
• Aligning the two means CI catches what the cluster would reject.

10. Encode an incident branch as runnable checks

Turn a triage decision into commands the skill runs in order.

# ImagePullBackOff branch
kubectl describe pod api-7d9f | grep -A3 Events
kubectl get events --field-selector reason=Failed

• describe events distinguish a bad tag, a missing secret, or a registry outage.
• A reason=Failed event with "not found" points to a wrong image reference.
• An "unauthorized" message points to a missing or wrong imagePullSecret.
• The skill maps each message to a specific, documented fix.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).