okteto-onboarding

Okteto Onboarding Skill

1. Activation

This skill activates when all of the following are true:

• The project has no okteto.yaml or okteto.yml at the repo root
• The user is asking about Okteto, dev environments, or onboarding (e.g., "how do I get this onto Okteto", "set this repo up for Okteto", "create an Okteto manifest")

Do NOT activate if:

• An okteto.yaml or okteto.yml already exists at the repo root — that is the existing okteto skill's domain. Defer to it.
• The user is asking how to use Okteto with an existing manifest. Defer to the existing okteto skill.

Pre-flight check. Before starting Phase 1, run:

ls okteto.yaml okteto.yml 2>/dev/null

If anything is returned, stop and tell the user:

"I see okteto.yaml already exists. The okteto-onboarding skill is for repos without a manifest. For working with the existing manifest, use the okteto skill or run /dev-setup."

Two operating modes: collaborative (default — user is in the loop) and autonomous (no human; opens a PR). See Section 7. Most of the workflow is mode-agnostic; only Phase 6 and the resolution of "ask the user" branches differ.

2. Phase 1 — Discover

Build an internal model of the repo: services, their build contexts, ports, dev commands, and any existing deploy artifacts. Read signals in priority order. Do not write the manifest yet.

2.1 Signal priority

1. docker-compose.yml / compose.yaml — the richest signal for services and dev, and a valid deploy: source on its own. If present, it is the primary blueprint for build: and dev:, and Okteto can deploy it directly via deploy: compose: (Section 4.1) — no chart or k8s manifests required. See the mapping table below.
2. Existing Helm chart — any Chart.yaml under chart/, charts/, helm/, or deploy/. If found, deploy: will be a helm upgrade --install command. Do not generate or modify the chart.
3. Existing k8s manifests — .yaml files with kind: headers under k8s/, manifests/, deploy/ — but excluding any templates/ subdirectory (those belong to a Helm chart and are not directly applyable). If found, deploy: will be kubectl apply -f .... Do not author these manifests.
4. Per-service Dockerfiles — for repos without compose, each top-level Dockerfile is a candidate service. Service name comes from the parent directory.
5. Language manifests — package.json, go.mod, pom.xml, pyproject.toml, Gemfile, Cargo.toml. Used to pick the dev image and infer the dev command. When this is the only signal (no Dockerfile, no compose), name the service after the project's name field (e.g., pyproject.toml's [project] name, package.json's name) or, failing that, the repo directory.
6. Procfile / Makefile — secondary signals when language manifests are ambiguous.