Before doing anything else: Fully resolve all variables in ## Context to resolve before acting. Do not begin Step 0 until every variable has a concrete value.
Silent failure — check this before any other step:
If the application has ddtrace, dd-trace, or any OpenTelemetry SDK in its dependency manifest (requirements.txt, package.json, Gemfile, go.mod, pom.xml) — even with no import statements in code — SSI will silently disable itself at runtime.
The failure is invisible: init containers run and complete, the pod starts healthy, no errors appear in kubectl or pup, but no traces arrive. The injector detects the user-installed tracer and exits cleanly without logging anything.
If any match — stop. Remove the package entirely (not just the import), rebuild the image, reload it into the cluster, and restart the pod before continuing. A package present in the manifest is enough to trigger this even if it is never imported.
Discover from the cluster — do not ask the user for information you can find yourself.
Variable
How to resolve
AGENT_NAMESPACE
Same namespace used in agent-install (e.g. datadog)
APP_NAMESPACE
Run kubectl get namespaces --no-headers | awk '{print $1}' | grep -vE '^(kube-system|kube-public|kube-node-lease|datadog|local-path-storage)$' — instrument all non-system namespaces, or use the namespace(s) the user mentioned
TARGET_LANGUAGES
Run kubectl get pods -A -o jsonpath='{.items[*].spec.containers[*].image}' and infer language from image names, or check Dockerfiles/manifests in the workspace. If uncertain, enable all languages.
DEPLOYMENT_NAME
Run kubectl get deployments -A --no-headers — identify application deployments (exclude system components)
APP_LABEL
Check spec.selector.matchLabels in the Deployment manifest via kubectl get deployment <DEPLOYMENT_NAME> -n <APP_NAMESPACE> -o yaml
CLUSTER_NAME
Check spec.global.clusterName in datadog-agent.yaml, or kubectl config current-context — needed for kind clusters in Step 0
ENV
Use apm-evals if running in an eval cluster (kind cluster names contain “evalya”). Otherwise use production unless the user specifies otherwise.
SERVICE_NAME
Use the deployment name (e.g. python-app → service python-app). Do not ask the user.
[DECISION: how does this cluster get local images?]
Check the repo’s setup script (e.g. create.sh, Makefile, justfile) for how images are loaded — do not guess from the cluster name or context. Common patterns:
What you find in the setup script
Load command
minikube image load or minikube cache add
minikube -p <PROFILE> image load <IMAGE_NAME> — profile is the -p flag value in the script, NOT necessarily the kubectl context name
Push the new image; the cluster will pull on restart — skip local load
k3d image import
k3d image import <IMAGE_NAME> -c <CLUSTER_NAME>
No image load step (cloud cluster, always pulls from registry)
Skip — image will be pulled on next deployment
If the setup script is ambiguous, run the load command it uses exactly as written.
Registry-based: skip — image will be pulled on next deployment
Confirm with the user before restarting. Tell the user: “I need to restart <DEPLOYMENT_NAME> in <APP_NAMESPACE> to pick up the rebuilt image. Ready to proceed?” Wait for confirmation.
SSI is configured on the existing DatadogAgent resource — do not create a separate manifest.
Choose targeting scope based on what the user asked for:
User asked to instrument all applications or didn’t specify scope → use Option A (cluster-wide)
User asked for specific namespaces only → use Option B
User asked to exclude namespaces from cluster-wide → use Option C
User asked for specific pods/workloads → use Option D
Default is cluster-wide (Option A). If the user said “all my applications”, “my whole cluster”, or didn’t restrict scope, use Option A with no enabledNamespaces or targets.
Note:ddTraceVersions only applies inside a targets[] entry (Option D). It is not valid alongside enabledNamespaces or at the instrumentation level directly.
Do NOT modify application Deployments without explicit user confirmation. Applying labels to existing application workloads is a change to customer-managed resources.
Inform the user that adding Unified Service Tags (UST) to their Deployments will enable proper service/env/version tagging in Datadog. This is optional for SSI to work but recommended for full observability:
yaml
# Add to both metadata.labels and spec.template.metadata.labelstags.datadoghq.com/env: "<ENV>"tags.datadoghq.com/service: "<SERVICE_NAME>"tags.datadoghq.com/version: "<VERSION>"
If the user wants you to apply these, get their confirmation first. UST labels are not required for APM traces to flow — SSI works without them.
Confirm with the user before restarting. Tell the user: “I need to restart <DEPLOYMENT_NAME> in <APP_NAMESPACE> for SSI to inject into the pods. This will cause a brief outage. Ready to proceed?” Wait for confirmation.
Never write a raw API key into any file or chat message
Never use namespace default for Datadog resources
Never modify admissionController settings directly — SSI manages this via the Operator
Do not add APM config to application manifests — configure only via DatadogAgent
Exception: UST labels (tags.datadoghq.com/*) on application Deployments are required and intentional
Never run kubectl delete without user confirmation
docker push to a registry always requires user confirmation
Never use kubectl patch to apply UST labels or any Deployment changes. Always edit the Deployment YAML file and kubectl apply -f. Changes made with kubectl patch are transient and will be overwritten on the next rollout.
About this skill
Trigger
Enable Single Step Instrumentation (SSI) on Kubernetes — automatically instruments applications for APM without code changes. Only use if the Datadog Agent is already running on the cluster — if not, use agent-install first.
The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.
MIT — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.
Discovery
48 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. 11 distinct layouts observed: agent-observability/*/SKILL.md, */SKILL.md, dd-apm/k8s-ssi/*/SKILL.md, dd-apm/linux-ssi/*/SKILL.md, dd-apm/*/SKILL.md, dd-apps/*/SKILL.md, dd-audit/*/SKILL.md, dd-browser-sdk/*/SKILL.md, dd-security/csm/*/SKILL.md, dd-software-delivery/*/SKILL.md, SKILL.md (repo root).
Issue colours
Resolved from a curated brand profile — hue 299°, chroma 0.183. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.
Heading repairs
2 repairs applied to this skill so the document has one h1 and no skipped levels:
Shifted “15 headings” from h1 to h2 so the skill title is the only h1.
Repaired “Claude runs” from h4 to h3, closing a skipped level.
Spec compliance
12 editorial notes across 12 of 48 skills. They are printed in the margin of each skill rather than as errors here.
Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.
Signal
Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.
Agent surfaces
The whole issue is available as one markdown document at /datadog-labs/agent-skills.md, and each skill at its own .md URL.
Publication
Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.