Agent Skills Best Practices

Packaged SME skills only pay off when they are trustworthy, and trust comes from being version-pinned, narrowly scoped, and honest about uncertainty.

How to Use This List

Read it once end to end before you write your first skill, because the scoping decisions in group A are expensive to reverse later.

After that, treat it as a review checklist for any skill headed to a shared repository.

Each practice is written for a skill that reviews Docker or Kubernetes artifacts - Dockerfile review, manifest lint, incident triage - but the structural advice generalizes.

A - Scope and Boundaries

Give each skill one job. A Dockerfile reviewer that also lints manifests and triages incidents will do all three badly, and its findings become impossible to tune.

Decide read-only versus write-capable up front. Review and triage skills should be read-only against production; a skill that can restart a workload during an incident needs a much higher bar of review.

Name the artifact the skill consumes. "Rendered Kubernetes YAML" is a scope; "Kubernetes stuff" is not, and the difference shows up as false positives on Helm template text.

Stop at the boundary of your evidence. A triage skill that reaches "the process exited 1 with this stack trace" should hand off to a human rather than speculate about application logic.

Prefer composition over one large skill. A manifest skill that shells out to kubeconform and kube-linter inherits their maintenance instead of duplicating it.

B - Version Pinning

Pin the skill to a Kubernetes minor. Validate against 1.36.2 explicitly rather than "latest", because a schema check that floats will start failing on fields your clusters do not have yet.

Pin the Pod Security Standards version target. Use pod-security.kubernetes.io/enforce-version: v1.36 in both the namespace and the skill's expectations, so a cluster upgrade cannot silently tighten admission underneath you.

Pin the tool versions the skill orchestrates. A Trivy or hadolint upgrade changes findings, and an unpinned tool turns a stable pipeline into a flaky one.

Version the skill itself and record it in output. Every finding should name the skill version that produced it, or you cannot explain why yesterday's clean build fails today.

Bump the pins deliberately, as part of the cluster upgrade. Treat the skill's target version as an artifact of your platform version, reviewed and rolled out together.

Track the supported skew. Kubernetes supports 1.34 through 1.36 today with 1.33 EOL, so a skill validating against a version outside that window is testing against a cluster nobody runs.

C - Findings Quality

Every finding needs a rationale and a fix. "Missing readiness probe" is a complaint; "missing readiness probe, so traffic reaches the pod before it can serve, add this block" is a review.

Separate blocking from advisory. Leaked secrets and root containers block; cache ordering and label conventions warn. Conflating them trains people to bypass the skill entirely.

Cite the evidence. A triage skill should quote the exitCode: 137 and reason: OOMKilled it read, not just assert an OOM kill.

Make findings deterministic. The same input must produce the same output, or nobody can tell a real regression from noise.

Say "I do not know" explicitly. A skill that always produces a confident diagnosis is a skill that fabricates one when the evidence runs out.

Keep the output diffable. Stable ordering and stable IDs let CI comment only on new findings instead of re-posting the entire report every push.

D - Integration and Enforcement

Run review skills in CI, not just locally. A skill that only runs when someone remembers to run it is documentation with extra steps.

Render before you lint. helm template or kustomize build first, because the API server never sees your Go templates.

Back CI checks with admission control. Kyverno or OPA Gatekeeper enforces the same rules at the cluster boundary and covers the manifests that never went through your pipeline.

Do not duplicate rules across CI and admission. Generate both from one source of truth, or they will drift and teams will trust neither.

Enrich alerts rather than paging on skill output. Attach triage findings to the existing page; a skill that pages on its own becomes another alert to tune.

E - Maintenance and Trust

Measure the false positive rate. A skill above roughly ten percent noise gets ignored, and an ignored skill is worse than none because it implies coverage that does not exist.

Give every rule an owner and a documented rationale. Rules without a stated reason survive long past their usefulness and nobody feels safe deleting them.

Provide a scoped, expiring exception path. Per-resource annotations with an owner and a review date beat a global disable flag that quietly becomes permanent.

Test the skill against known-good and known-bad fixtures. Keep a corpus of manifests and Dockerfiles with expected findings, and run it in the skill's own CI.

Delete rules that never fire. A rule with zero hits across a year of builds is either already solved by defaults or wrong.

Roll out new rules in warn mode first. Measure the blast radius on real repositories before flipping a rule to blocking.

When You Are Done

Your skill should have one clearly stated job, a pinned Kubernetes minor and PSS version target, and findings that carry evidence plus a fix.

It should run in CI on rendered output, be backed by an admission controller for the rules that truly matter, and have a fixture suite that fails when its behavior changes.

If you cannot answer "what does this skill refuse to decide", the scope is not tight enough yet.

FAQs

How strictly should we pin the Kubernetes minor?

To the exact minor your clusters run, currently 1.36.2. Patch drift is safe; minor drift changes schemas and admission behavior.

Should skills block merges?

For hard security failures, yes. For style and efficiency findings, warn, or you will teach your teams to reach for the bypass.

How many rules should a skill have?

Fewer than you think. A dozen well-chosen, low-noise rules that people act on beat sixty that get skimmed.

Where do exceptions live?

On the resource, as an annotation with an owner and an expiry, so they are visible in review rather than buried in a config file.

Do we still need admission control if CI is green?

Yes. CI covers what goes through CI; admission covers everything, including the emergency kubectl apply at 2am.

How do we keep the skill from drifting from the platform?

Own it in the same repository and release cycle as your cluster version bumps, so the pins move as one deliberate change.

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).

Agent Skills Best Practices

Packaged SME skills only pay off when they are trustworthy, and trust comes from being version-pinned, narrowly scoped, and honest about uncertainty.

How to Use This List

Read it once end to end before you write your first skill, because the scoping decisions in group A are expensive to reverse later.

After that, treat it as a review checklist for any skill headed to a shared repository.

Each practice is written for a skill that reviews Docker or Kubernetes artifacts - Dockerfile review, manifest lint, incident triage - but the structural advice generalizes.

A - Scope and Boundaries

Give each skill one job. A Dockerfile reviewer that also lints manifests and triages incidents will do all three badly, and its findings become impossible to tune.

Name the artifact the skill consumes. "Rendered Kubernetes YAML" is a scope; "Kubernetes stuff" is not, and the difference shows up as false positives on Helm template text.

Stop at the boundary of your evidence. A triage skill that reaches "the process exited 1 with this stack trace" should hand off to a human rather than speculate about application logic.

Prefer composition over one large skill. A manifest skill that shells out to kubeconform and kube-linter inherits their maintenance instead of duplicating it.

B - Version Pinning

Pin the skill to a Kubernetes minor. Validate against 1.36.2 explicitly rather than "latest", because a schema check that floats will start failing on fields your clusters do not have yet.

Pin the tool versions the skill orchestrates. A Trivy or hadolint upgrade changes findings, and an unpinned tool turns a stable pipeline into a flaky one.

Version the skill itself and record it in output. Every finding should name the skill version that produced it, or you cannot explain why yesterday's clean build fails today.

Bump the pins deliberately, as part of the cluster upgrade. Treat the skill's target version as an artifact of your platform version, reviewed and rolled out together.

Track the supported skew. Kubernetes supports 1.34 through 1.36 today with 1.33 EOL, so a skill validating against a version outside that window is testing against a cluster nobody runs.

C - Findings Quality

Every finding needs a rationale and a fix. "Missing readiness probe" is a complaint; "missing readiness probe, so traffic reaches the pod before it can serve, add this block" is a review.

Separate blocking from advisory. Leaked secrets and root containers block; cache ordering and label conventions warn. Conflating them trains people to bypass the skill entirely.

Cite the evidence. A triage skill should quote the exitCode: 137 and reason: OOMKilled it read, not just assert an OOM kill.

Make findings deterministic. The same input must produce the same output, or nobody can tell a real regression from noise.

Say "I do not know" explicitly. A skill that always produces a confident diagnosis is a skill that fabricates one when the evidence runs out.

Keep the output diffable. Stable ordering and stable IDs let CI comment only on new findings instead of re-posting the entire report every push.

D - Integration and Enforcement

Run review skills in CI, not just locally. A skill that only runs when someone remembers to run it is documentation with extra steps.

Render before you lint. helm template or kustomize build first, because the API server never sees your Go templates.

Back CI checks with admission control. Kyverno or OPA Gatekeeper enforces the same rules at the cluster boundary and covers the manifests that never went through your pipeline.

Do not duplicate rules across CI and admission. Generate both from one source of truth, or they will drift and teams will trust neither.

Enrich alerts rather than paging on skill output. Attach triage findings to the existing page; a skill that pages on its own becomes another alert to tune.

E - Maintenance and Trust

Measure the false positive rate. A skill above roughly ten percent noise gets ignored, and an ignored skill is worse than none because it implies coverage that does not exist.

Give every rule an owner and a documented rationale. Rules without a stated reason survive long past their usefulness and nobody feels safe deleting them.

Provide a scoped, expiring exception path. Per-resource annotations with an owner and a review date beat a global disable flag that quietly becomes permanent.

Test the skill against known-good and known-bad fixtures. Keep a corpus of manifests and Dockerfiles with expected findings, and run it in the skill's own CI.

Delete rules that never fire. A rule with zero hits across a year of builds is either already solved by defaults or wrong.

Roll out new rules in warn mode first. Measure the blast radius on real repositories before flipping a rule to blocking.

When You Are Done

Your skill should have one clearly stated job, a pinned Kubernetes minor and PSS version target, and findings that carry evidence plus a fix.

It should run in CI on rendered output, be backed by an admission controller for the rules that truly matter, and have a fixture suite that fails when its behavior changes.

If you cannot answer "what does this skill refuse to decide", the scope is not tight enough yet.

FAQs

How strictly should we pin the Kubernetes minor?

To the exact minor your clusters run, currently 1.36.2. Patch drift is safe; minor drift changes schemas and admission behavior.

Should skills block merges?

For hard security failures, yes. For style and efficiency findings, warn, or you will teach your teams to reach for the bypass.

How many rules should a skill have?

Fewer than you think. A dozen well-chosen, low-noise rules that people act on beat sixty that get skimmed.

Where do exceptions live?

On the resource, as an annotation with an owner and an expiry, so they are visible in review rather than buried in a config file.

Do we still need admission control if CI is green?

Yes. CI covers what goes through CI; admission covers everything, including the emergency kubectl apply at 2am.

How do we keep the skill from drifting from the platform?

Own it in the same repository and release cycle as your cluster version bumps, so the pins move as one deliberate change.

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).

Agent Skills Best Practices

Search Documentation

Agent Skills Best Practices