okteto-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Okteto Onboarding Skill

Okteto 入门技能

1. Activation

1. 触发条件

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:

bash

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.

当且仅当以下所有条件满足时，本技能被触发：

项目仓库根目录不存在
```
okteto.yaml
```
或
```
okteto.yml
```
文件
用户询问与Okteto、开发环境或项目接入相关的问题（例如“如何将此项目部署到Okteto”“为这个仓库配置Okteto环境”“创建Okteto清单文件”）

请勿触发的场景：

仓库根目录已存在
```
okteto.yaml
```
或
```
okteto.yml
```
文件——此类场景属于现有
```
okteto
```
技能的处理范畴，请转交至该技能。
用户询问如何结合现有清单文件使用Okteto——请转交至现有
```
okteto
```
技能。

预检查步骤：在进入第一阶段前，执行以下命令：

bash

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

如果命令返回结果，请立即停止并告知用户：

"我发现当前仓库已存在
okteto.yaml
文件。
okteto-onboarding
技能仅适用于无清单文件的仓库。如需基于现有清单文件进行操作，请使用
okteto
技能或执行
/dev-setup
命令。"

两种运行模式：协作模式（默认模式——用户全程参与）和自主模式（无需人工干预，直接创建PR）。详情见第7节。大部分工作流与模式无关，仅第6阶段和“询问用户”分支的处理逻辑有所差异。

2. Phase 1 — Discover

2. 第一阶段：项目探测

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

2.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.
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.
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.
Per-service Dockerfiles — for repos without compose, each top-level
```
Dockerfile
```
is a candidate service. Service name comes from the parent directory.
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.
Procfile / Makefile — secondary signals when language manifests are ambiguous.

These signals are complementary, not exclusive. A repo can carry more than one. Common combinations:

Compose only — compose drives
```
build:
```
,
```
dev:
```
, and
```
deploy:
```
(via
```
deploy: compose:
```
). Enough to reach Level 2 with no chart or k8s manifests.
Chart or k8s only — the artifact drives
```
deploy:
```
; derive
```
dev:
```
from the deployed workload names (Phase 3, bullet 4).
Compose and a chart/k8s — the deploy source is ambiguous. Compose files are often the dev path and charts the prod path, but not always. Do not assume the chart wins
deploy:
. Ask the user which should drive it — compose, the chart/manifests, or both combined (Section 2.5).

Apply each signal to its own section of the manifest rather than treating priority order as a winner-takes-all.

Don't stop at the root compose file. Real projects routinely ship several: a base or production compose (often at the repo root, using published

image:

s) plus one or more development composes under

docker/

dev/

, or named

*.dev.yml

compose.dev.yml

. Glob for

**/docker-compose*.y*ml

and

**/compose*.y*ml

(skip

node_modules

, vendor, and build dirs) — not just

./docker-compose.yml

. The split usually maps cleanly:

The dev compose — the one that builds from source (
```
build:
```
with
```
context:
```
/
```
target:
```
, plus source bind mounts) — drives
```
build:
```
and
```
dev:
```
.
A base / production /
*.preview*
compose can drive
```
deploy:
```
.

When more than one compose file exists, list them and ask which describes development and which is the deploy source (Section 2.5). Do not assume the root file is the dev blueprint — a root compose built entirely from published images is a run/deploy file, and developing against a published image is meaningless.

Follow
include:
and resolve anchors. A compose file may pull in others via

include:

(or the older

extends:

) — read those too, or you'll miss services. Parse the resolved YAML, not raw lines: dev composes commonly rely on anchors and

x-

extension fields (

build: *some-anchor

<<: *some-env

), which only make sense after expansion.

An existing Okteto-aware compose is a strong signal. If a compose file already uses Okteto Compose extensions (

endpoints:

public:

) or is clearly an okteto deploy file, prefer it as the

deploy:

source and surface it to the user rather than authoring something new — the customer has already expressed how they want to deploy.

docker-compose.yml
/
compose.yaml
——是服务和开发场景最丰富的信号源，本身可直接作为
```
deploy:
```
的数据源。如果存在，它将作为
```
build:
```
和
```
dev:
```
的主要蓝图，Okteto可通过
```
deploy: compose:
```
直接部署（见第4.1节）——无需Helm Chart或k8s清单文件。详见下方映射表。
现有Helm Chart——位于
```
chart/
```
、
```
charts/
```
、
```
helm/
```
或
```
deploy/
```
目录下的任意
```
Chart.yaml
```
文件。如果找到，
```
deploy:
```
将使用
```
helm upgrade --install
```
命令。请勿生成或修改Chart文件。
现有k8s清单文件——位于
```
k8s/
```
、
```
manifests/
```
、
```
deploy/
```
目录下且包含
```
kind:
```
头的
```
.yaml
```
文件——但需排除
templates/
子目录（该目录属于Helm Chart，无法直接应用）。如果找到，
```
deploy:
```
将使用
```
kubectl apply -f ...
```
命令。请勿编写此类清单文件。
按服务划分的Dockerfile——对于无compose文件的仓库，每个顶级
```
Dockerfile
```
对应一个候选服务，服务名称取自其父目录。
语言清单文件——
```
package.json
```
、
```
go.mod
```
、
```
pom.xml
```
、
```
pyproject.toml
```
、
```
Gemfile
```
、
```
Cargo.toml
```
。用于选择开发镜像并推断开发命令。当这是唯一信号源（无Dockerfile、无compose）时，服务名称取自项目的
```
name
```
字段（例如
```
pyproject.toml
```
的
```
[project] name
```
、
```
package.json
```
的
```
name
```
），若无法获取则使用仓库目录名称。
Procfile / Makefile——当语言清单文件存在歧义时作为辅助信号。

这些信号是互补关系，而非互斥关系。一个仓库可同时包含多种信号。常见组合：

仅含compose文件——compose文件驱动
```
build:
```
、
```
dev:
```
和
```
deploy:
```
（通过
```
deploy: compose:
```
）。无需Chart或k8s清单文件即可达到Level 2。
仅含Chart或k8s清单——工件驱动
```
deploy:
```
；从已部署的工作负载名称推导
```
dev:
```
（见第3阶段第4点）。
同时含compose和Chart/k8s清单——部署源存在歧义。Compose文件通常用于开发流程，Chart用于生产流程，但并非绝对。请勿默认选择Chart作为
deploy:
的数据源。请询问用户应使用哪一个——compose、Chart/清单文件，还是两者结合（见第2.5节）。

将每个信号应用到清单文件的对应部分，而非将优先级顺序视为“赢家通吃”。

不要仅读取根目录的compose文件。实际项目通常包含多个compose文件：一个基础或生产环境compose（通常位于仓库根目录，使用已发布的

image:

），加上一个或多个位于

docker/

、

dev/

目录下的开发环境compose，或命名为

*.dev.yml

compose.dev.yml

的文件。请全局搜索

**/docker-compose*.y*ml

和

**/compose*.y*ml

（跳过

node_modules

、vendor和构建目录）——而非仅搜索

./docker-compose.yml

。通常可按以下规则区分：

开发环境compose——即从源码构建的compose文件（包含
```
build:
```
块及
```
context:
```
/
```
target:
```
，加上源码绑定挂载）——驱动
```
build:
```
和
```
dev:
```
。
基础/生产/
*.preview*
环境compose——可驱动
```
deploy:
```
。

当存在多个compose文件时，列出所有文件并询问用户哪一个描述开发流程，哪一个作为部署源（见第2.5节）。请勿默认根目录文件为开发蓝图——完全基于已发布镜像构建的根目录compose是一个运行/部署文件，针对已发布镜像进行开发毫无意义。

解析
include:
和锚点。compose文件可能通过

include:

（或旧版

extends:

）引入其他文件——请一并读取这些文件，否则会遗漏服务。解析已展开的YAML，而非原始行：开发环境compose通常依赖锚点和

x-

扩展字段（例如

build: *some-anchor

、

<<: *some-env

），这些内容只有在展开后才有意义。

已支持Okteto的compose文件是强信号。如果compose文件已使用Okteto Compose扩展（

endpoints:

、

public:

）或明显是Okteto部署文件，请优先将其作为

deploy:

的数据源并告知用户，而非重新创建——客户已明确表达了他们希望的部署方式。

2.2 Compose → Okteto mapping

2.2 Compose → Okteto 字段映射

When

docker-compose.yml

is present, map fields like this:

Compose field	Okteto manifest field
`services.<name>`	`build.<name>` (when there's a `build:` block) and `dev.<name>`
`build.context` , `build.dockerfile`	`build.<name>.context` , `build.<name>.dockerfile`
`image` (no `build` )	`dev.<name>.image` directly — do not add a `build.<name>` entry for pre-built images
`ports` (Level 1)	`dev.<name>.forward` — preserves the user's local-port intent
`ports` (Level 2+)	exposed via the `deploy:` source (compose `deploy:` , Helm, or k8s); also keep `dev.<name>.forward` for active dev sessions
`command`	starting point for `dev.<name>.command`
`volumes` (host bind mounts only)	`dev.<name>.sync` candidates
`depends_on`	ordering hint for the deploy step
`environment`	`dev.<name>.environment`

Ignore compose-only concepts that don't translate (

networks

restart

, named volumes,

extends

Backing services vs. dev targets. A compose service that uses a published

image:

with no

build:

and no source in the repo (databases, caches, object stores, mail catchers, message brokers —

postgres

redis

minio

nats

mailpit

, and the like) is infrastructure: include it in the

deploy:

stack, but it rarely belongs in

dev:

. Reserve

dev:

for the services you actually edit — the ones that build from source in the repo. Don't create a
dev:
entry for every compose service by default; a repo with ten compose services often has only one or two real dev targets.

当存在

docker-compose.yml

文件时，按以下规则映射字段：

Compose字段	Okteto清单字段
`services.<name>`	`build.<name>` （当存在 `build:` 块时）和 `dev.<name>`
`build.context` , `build.dockerfile`	`build.<name>.context` , `build.<name>.dockerfile`
`image` （无 `build:` 块）	直接映射到 `dev.<name>.image` ——请勿为预构建镜像添加 `build.<name>` 条目
`ports` （Level 1）	`dev.<name>.forward` ——保留用户的本地端口映射意图
`ports` （Level 2+）	通过 `deploy:` 数据源（compose `deploy:` 、Helm或k8s）暴露；同时保留 `dev.<name>.forward` 用于活跃开发会话
`command`	作为 `dev.<name>.command` 的起始值
`volumes` （仅主机绑定挂载）	`dev.<name>.sync` 的候选值
`depends_on`	部署步骤的顺序提示
`environment`	`dev.<name>.environment`

忽略无法映射的compose专属概念（

networks

、

restart

、命名卷、

extends

）。

后台服务 vs 开发目标。使用已发布

image:

且无

build:

块、仓库中无对应源码的compose服务（数据库、缓存、对象存储、邮件捕获器、消息队列——例如

postgres

、

redis

、

minio

、

nats

、

mailpit

等）属于基础设施：需将其包含在

deploy:

栈中，但通常无需加入

dev:

。

dev:

仅用于实际需要编辑的服务——即从仓库源码构建的服务。请勿默认将所有compose服务加入
dev:
；一个包含10个compose服务的仓库通常只有1-2个真正的开发目标。

2.3 Dev-image picks by language manifest

2.3 基于语言清单文件选择开发镜像

Pick the image family from the language manifest, and the tag from the version the repo declares — do not hard-code a version. Reading the declared version keeps the pick current instead of freezing a minor that goes stale.

Language manifest	Image family	Where to read the version
`package.json`	`okteto/node`	`engines.node`
`go.mod`	`okteto/golang`	the `go 1.x` line
`pom.xml` / `build.gradle*`	`okteto/maven` or `okteto/gradle`	`maven.compiler.release` / `sourceCompatibility` , or the wrapper version
`pyproject.toml` / `requirements.txt`	`okteto/python`	`requires-python` or `.python-version`
`Gemfile`	`okteto/ruby`	`.ruby-version` or the `ruby` directive
`Cargo.toml`	`okteto/rust`	`rust-version` (MSRV), if set

Tag the image with the declared version, e.g.

okteto/golang:1.23

when

go.mod

says

go 1.23

. State the source in an inline comment (

# go.mod declares Go 1.23

When the repo declares no version, do not invent a specific minor — it will be wrong as often as right. In collaborative mode, ask the user which version they target. In autonomous mode, pin to the family's current stable major and flag it in the PR as a decision to confirm (

# go.mod has no version line — defaulting to a recent stable; confirm

从语言清单文件中选择镜像家族，并从仓库声明的版本中选择标签——请勿硬编码版本。读取声明的版本可确保镜像选择保持最新，避免使用过时的次要版本。

语言清单文件	镜像家族	版本读取位置
`package.json`	`okteto/node`	`engines.node`
`go.mod`	`okteto/golang`	`go 1.x` 行
`pom.xml` / `build.gradle*`	`okteto/maven` 或 `okteto/gradle`	`maven.compiler.release` / `sourceCompatibility` ，或wrapper版本
`pyproject.toml` / `requirements.txt`	`okteto/python`	`requires-python` 或 `.python-version`
`Gemfile`	`okteto/ruby`	`.ruby-version` 或 `ruby` 指令
`Cargo.toml`	`okteto/rust`	`rust-version` （MSRV，若已设置）

使用声明的版本标记镜像，例如当

go.mod

中声明

go 1.23

时，使用

okteto/golang:1.23

。需在注释中注明版本来源（例如

# go.mod declares Go 1.23

）。

当仓库未声明版本时，请勿随意指定次要版本——错误概率很高。在协作模式下，请询问用户目标版本。在自主模式下，固定为镜像家族当前稳定的主版本，并在PR中标记为需确认的决策（例如

# go.mod has no version line — defaulting to a recent stable; confirm

）。

2.4 Dev-command picks

2.4 开发命令选择

Signal	Dev command default
`package.json` with `scripts.dev`	`npm run dev`
`package.json` with `scripts.start` (no dev)	`npm start`
`go.mod`	`bash` (Go projects usually want a shell to `go run` manually)
`pom.xml` with `spring-boot-maven-plugin`	`mvn spring-boot:run`
`pyproject.toml` with FastAPI/Flask	`bash` (varies too much to default)
Procfile with a `web:` line	the value of `web:`
compose `entrypoint` / `command` is `sleep infinity` or `tail -f /dev/null`	`bash` — this is a dev-container placeholder (the container stays alive so you exec in), not a real command. Don't copy it into `dev.<svc>.command` ; it's exactly the pattern Okteto's `dev:` replaces.
None of the above	`bash`

信号源	默认开发命令
含 `scripts.dev` 的 `package.json`	`npm run dev`
含 `scripts.start` 但无 `scripts.dev` 的 `package.json`	`npm start`
`go.mod`	`bash` （Go项目通常需要shell手动执行 `go run` ）
含 `spring-boot-maven-plugin` 的 `pom.xml`	`mvn spring-boot:run`
含FastAPI/Flask的 `pyproject.toml`	`bash` （差异较大，无法默认）
含 `web:` 行的Procfile	`web:` 对应的值
compose的 `entrypoint` / `command` 为 `sleep infinity` 或 `tail -f /dev/null`	`bash` ——这是开发容器占位符（保持容器存活以便进入执行命令），而非真实命令。请勿将其复制到 `dev.<svc>.command` ；这正是Okteto的 `dev:` 要替代的模式。
以上均不满足	`bash`

2.5 When discovery is ambiguous

2.5 探测结果存在歧义时的处理

If discovery leaves real ambiguity, ask one targeted question at a time rather than guessing. Examples:

"I see Dockerfiles in
```
api/
```
and
```
web/
```
but no compose file. Should both be services?"
"I found a Helm chart at
```
chart/
```
and another at
```
infra/helm/
```
. Which one is the canonical deploy?"
"This repo has both a
```
docker-compose.yml
```
and a Helm chart. Which should drive
```
deploy:
```
— the compose file, the chart, or both? (Compose is often the dev path and the chart the prod path, but I don't want to assume.)"
"I see several compose files —
```
docker-compose.yml
```
at the root and
```
docker/docker-compose.dev.yml
```
. Which one describes how you develop (builds from source), and which should I use to deploy the stack?"
"Your
```
package.json
```
doesn't have a
```
scripts.dev
```
— what command starts your dev server?"

Do not ask the user about everything. Only ask when a guess would be likely wrong. Trust the signals.

In autonomous mode, do not ask. Pick the most conservative interpretation, proceed, and note the ambiguity in the PR description (Section 7.2 covers this).

如果探测结果存在明确歧义，请一次只问一个针对性问题，而非猜测。示例：

"我在
```
api/
```
和
```
web/
```
目录下发现了Dockerfile，但未找到compose文件。是否应将两者都作为服务？"
"我在
```
chart/
```
和
```
infra/helm/
```
目录下都找到了Helm Chart。哪一个是标准的部署文件？"
"此仓库同时包含
```
docker-compose.yml
```
和Helm Chart。应使用哪一个驱动
```
deploy:
```
——compose文件、Chart，还是两者结合？（compose通常用于开发流程，Chart用于生产流程，但我不想随意假设。）"
"我发现多个compose文件——根目录的
```
docker-compose.yml
```
和
```
docker/docker-compose.dev.yml
```
。哪一个描述开发流程（从源码构建），哪一个用于部署栈？"
"你的
```
package.json
```
中没有
```
scripts.dev
```
——启动开发服务器的命令是什么？"

请勿询问用户所有问题。仅当猜测很可能出错时才询问。请信任探测到的信号。

在自主模式下，请勿询问。选择最保守的解释继续执行，并在PR描述中注明歧义（见第7.2节）。

2.6 Output of Phase 1

2.6 第一阶段输出

Internally, you should now have a model like:

Services: [api, web, worker]
api:    Dockerfile @ ./api,    port 8080, dev cmd `bash`,        dev image `okteto/golang:1.22`
web:    Dockerfile @ ./web,    port 3000, dev cmd `npm run dev`, dev image `okteto/node:20`
worker: Dockerfile @ ./worker, no port,   dev cmd `bash`,        dev image `okteto/python:3.12`
Deploy: helm chart at ./chart
Tests: detected `go test ./...` in api, `npm test` in web

Show this summary to the user before moving to Phase 2.

完成后，你应构建如下内部模型：

Services: [api, web, worker]
api:    Dockerfile @ ./api,    port 8080, dev cmd `bash`,        dev image `okteto/golang:1.22`
web:    Dockerfile @ ./web,    port 3000, dev cmd `npm run dev`, dev image `okteto/node:20`
worker: Dockerfile @ ./worker, no port,   dev cmd `bash`,        dev image `okteto/python:3.12`
Deploy: helm chart at ./chart
Tests: detected `go test ./...` in api, `npm test` in web

进入第二阶段前，请将此摘要展示给用户。

3. Phase 2 — Negotiate scope

3. 第二阶段：协商范围

Before drafting, frame the choice and pick a level on the adaptive ladder.

在起草清单文件前，向用户说明选项并选择适配层级。

3.1 The framing block (always show this to the user)

3.1 说明模块（必须展示给用户）

In Okteto,
deploy:
describes how to provision the environment — from a Docker Compose file, a Helm chart, or k8s manifests.
dev:
describes how to live-edit a running service — file sync, the dev image, the startup command. You can use Okteto with just
dev:
if you already have a way to deploy your stack, or have Okteto handle both.

This same framing goes at the top of the generated

okteto.yaml

as a header comment.

在Okteto中，
deploy:
描述如何部署环境——基于Docker Compose文件、Helm Chart或k8s清单文件。
dev:
描述如何实时编辑运行中的服务——文件同步、开发镜像、启动命令。如果已拥有部署栈的方式，可仅使用
dev:
；也可让Okteto同时处理部署和开发。

此说明需作为头部注释添加到生成的

okteto.yaml

文件顶部。

3.2 The adaptive ladder

3.2 适配层级

Level	What it produces	Requires
1 — dev-only	`dev:` section only. User runs their own deploy externally.	Nothing extra.
2 — deploy + dev	`build:` + `deploy:` + `dev:` . `okteto deploy` brings up the stack.	A Helm chart, k8s manifests, or a Docker Compose file in the repo.
3 — full lifecycle	Adds `test:` containers wired to existing test commands.	Level 2 prereqs PLUS detected tests.

层级	生成内容	要求
1 — 仅开发模式	仅 `dev:` 部分。用户需自行在外部部署环境。	无额外要求。
2 — 部署+开发模式	`build:` + `deploy:` + `dev:` 。执行 `okteto deploy` 即可启动栈。	仓库中存在Helm Chart、k8s清单文件或Docker Compose文件。
3 — 全生命周期模式	新增 `test:` 容器，与现有测试命令关联。	满足Level 2要求，且已探测到测试用例。

3.3 Recommendation logic

3.3 推荐逻辑

Recommend a level based on what Phase 1 found:

A deploy source is a Helm chart, k8s manifests, or a deployable Docker Compose file.

A deploy source found AND tests detected → recommend Level 3
A deploy source found, no tests → recommend Level 2
No deploy source at all (no chart, no k8s manifests, no compose) → recommend Level 1 (and explain why higher levels are unavailable)

When more than one deploy source exists (e.g. compose and a chart), confirm which one drives

deploy:

(Section 2.5) before drafting — don't default to the chart.

Then ask the user (collaborative mode) or accept the recommendation (autonomous mode):

"Based on what I found, I'd recommend Level [N]. Want to go with that, pick a different level, or have me explain the trade-offs?"

基于第一阶段的探测结果推荐层级：

部署源指Helm Chart、k8s清单文件或可部署的Docker Compose文件。

已找到部署源且探测到测试用例 → 推荐Level 3
已找到部署源但未探测到测试用例 → 推荐Level 2
未找到任何部署源（无Chart、无k8s清单、无compose） → 推荐Level 1（并说明无法使用更高层级的原因）

当存在多个部署源时（例如同时有compose和Chart），请先确认使用哪一个驱动

deploy:

（见第2.5节），再起草清单文件——请勿默认选择Chart。

然后询问用户（协作模式）或直接采用推荐层级（自主模式）：

"基于探测结果，我推荐使用Level [N]。是否采用此层级，还是选择其他层级，或需要我解释各层级的权衡？"

3.4 Locking the level

3.4 锁定层级

Once chosen, the level is locked for the rest of the session. Do not negotiate level mid-flight. If the draft turns out to need a different level (e.g., the chart is broken), surface that as a Phase 5 failure and re-enter Phase 2 cleanly.

一旦选定层级，在整个会话期间保持锁定。请勿在流程中途协商层级。如果草稿需要更换层级（例如Chart存在问题），请将其作为第五阶段的失败情况处理，并重新进入第二阶段。

4. Phases 3–4 — Draft and refine

4. 第三-四阶段：起草与优化

4.1 Draft (Phase 3)

4.1 起草（第三阶段）

Write

okteto.yaml

to the repo root. The user must see the actual file, not just a summary.

Required content of every draft:

Header comment block — the framing from Section 3.1, plus a note that the file was generated by
```
okteto-onboarding
```
and the user is expected to edit it. Include the chosen scope level and a one-line rationale.
build:
section (Level 2+) — one entry per service with
```
context
```
and
```
dockerfile
```
. Skip pre-built images here (they go directly under
```
dev.<svc>.image
```
).
deploy:
section (Level 2+) — points at the chosen deploy source:
- Compose:
```
deploy: { compose: docker-compose.yml }
```
  (optionally a
```
services:
```
  subset). The simplest path when the repo has no chart or manifests.
- Helm: a
```
helm upgrade --install
```
  command, passing built images via
```
--set ...=${OKTETO_BUILD_<SERVICE>_IMAGE}
```
  (see "Wiring built images" below).
- k8s manifests: a
```
kubectl apply -f ...
```
  command.
See the schema examples below.
dev:
section (always) — one entry per service the user wants in dev mode, with
```
image
```
,
```
command
```
, and
```
sync
```
. The key name must match the workload Okteto will deploy:
- Compose repo: the compose service name (mapping table, Section 2.2).
- Helm/k8s repo (no compose): the name of the Kubernetes workload the chart/manifests create — the
```
Deployment
```
  /
```
StatefulSet
```
```
metadata.name
```
  (render the chart or read the manifest to find it). A
```
dev:
```
  key matching no deployed workload won't attach.
The
```
image
```
,
```
command
```
, and
```
sync
```
come from the Dockerfile + language manifest (Sections 2.3–2.4) regardless of repo shape.
test:
section (Level 3) — one entry per detected test command. See the schema example below.

Sync-path defaults:

Single-service repo (one Dockerfile or one language manifest at the root):
```
.:/usr/src/app
```
is a reasonable default. If the Dockerfile sets
```
WORKDIR
```
, use that path on the right side instead of
```
/usr/src/app
```
.
Multi-service repo (per-service Dockerfiles or compose with multiple services): scope each service's sync to its own subdirectory, e.g.,
```
./api:/usr/src/app
```
. Syncing the whole repo into every container is almost always wrong.

Inline comments are required on every non-obvious choice (image picks, command picks, sync paths,

forward:

ports). Image and command picks are non-obvious by default — comment them.

Wiring built images into
deploy:
and
dev:
. Images defined under

build:

are pushed to the Okteto Registry and exposed to the rest of the manifest as environment variables:

```
OKTETO_BUILD_<SERVICE>_IMAGE
```
— full image reference (the one you almost always want)

OKTETO_BUILD_<SERVICE>_REGISTRY

_REPOSITORY

_SHA

— the parts, if you need them

<SERVICE>

is the

build:

key uppercased, with

replaced by

(so

build.web-api

→

OKTETO_BUILD_WEB_API_IMAGE

). Use these so the deployed workload runs the freshly built image instead of a stale or hard-coded one:

Helm:

--set api.image=${OKTETO_BUILD_API_IMAGE}

k8s manifests: substitute the value (e.g.
```
envsubst
```
) before
```
kubectl apply
```
, or template the image field.
Compose: the
```
build:
```
section already overrides the matching compose
```
image:
```
by service name — no
```
--set
```
needed.
dev:
: set
```
dev.<svc>.image: ${OKTETO_BUILD_<SVC>_IMAGE}
```
when the user wants to develop against the built application image rather than a generic toolchain image (Section 2.3).

Example: Level 2/3 fragment (build + deploy + dev + test)

yaml

build:
  api:
    context: ./api
    dockerfile: Dockerfile  # using the existing Dockerfile

deploy:
  - name: Deploy chart
    command: helm upgrade --install myapp ./chart --set api.image=${OKTETO_BUILD_API_IMAGE}  # built api image wired in

dev:
  api:
    image: okteto/golang:1.23  # tag from api/go.mod (go 1.23)
    command: bash               # Go services usually want a shell to `go run` manually
    sync:
      - ./api:/usr/src/app      # per-service sync; tighten if you have large generated dirs

test:
  api:
    image: okteto/golang:1.23
    context: ./api
    commands:
      - go test ./...           # detected from the project's test layout

Example: Level 2 fragment (compose-driven deploy, no chart)

yaml

build:
  api:
    context: ./api
    dockerfile: Dockerfile

deploy:
  compose: docker-compose.yml   # deploy the stack straight from compose — no chart or k8s manifests needed

dev:
  api:
    image: okteto/golang:1.23   # tag from api/go.mod (go 1.23)
    command: bash
    sync:
      - ./api:/usr/src/app

Compose-as-deploy caveats. A compose file written for local development often won't deploy cleanly to a cluster as-is. Before committing to

deploy: compose:

, scan the compose file and warn the user about:

Host-IP port bindings (e.g.
```
127.0.0.1:9229:9229
```
) — Okteto's compose deploy rejects them (
```
Host IP is not allowed
```
). Drop the host-IP prefix (
```
9229:9229
```
).
Source bind-mount volumes (e.g.
```
./api:/usr/local/app
```
) — on a cluster these become empty volumes that shadow the image's application code, so the service crashes (
```
can't open file 'app.py'
```
). They belong in
```
dev.<svc>.sync
```
, not in a deployed compose.

If the compose file leans on these dev-only constructs, surface it up front — don't discover it at deploy time. In preference order:

Generate a deploy-ready compose — derive a
```
compose.okteto.yaml
```
from the original with the cluster-hostile parts removed, and point
```
deploy: compose: compose.okteto.yaml
```
at it. See "Generating a deploy-ready compose" below.
Reuse an existing deploy compose — if the repo already ships one (e.g. a
```
*.preview*
```
or production compose without the dev volumes/ports), point
```
deploy: compose:
```
at that.
Use the chart/k8s manifests for
```
deploy:
```
instead, if the repo has them. This is why a repo with both compose and a chart often wants the chart for
```
deploy:
```
even though compose drives
```
dev:
```
(Section 2.5).

Generating a deploy-ready compose (
compose.okteto.yaml
). When compose is the chosen deploy source but the file carries dev-only constructs, write a derived copy rather than editing the user's original. This is a mechanical transform of the user's own file — not a hand-authored deploy artifact — so show it to the user as a diff against the source. Reference it explicitly:

deploy: { compose: compose.okteto.yaml }

. Apply these transforms:

Drop host-IP port prefixes —
```
127.0.0.1:9229:9229
```
→
```
9229:9229
```
. Debug-only ports (inspectors) can be removed entirely; they belong in
```
dev.<svc>.forward
```
.
Remove source bind-mount volumes —
```
./src:/app
```
and the like. The image already contains the code; these belong in
```
dev.<svc>.sync
```
. Keep named/data volumes (e.g.
```
db-data
```
).
Replace dev-container placeholders — a service whose
```
entrypoint
```
/
```
command
```
is
```
sleep infinity
```
won't run the app when deployed. Restore its real start command (from the Dockerfile
```
CMD
```
or a production compose), or drop the override.

Two things the transform cannot silently fix — flag these to the user rather than pretending the result is clean:

Host-path config/script mounts (e.g. an init script mounted as the container's entrypoint) — removing the mount doesn't make the service work; the file has to be baked into an image. Leave it and warn.
Anything else service-specific the scan can't reason about.

Add a header comment to

compose.okteto.yaml

: that it was derived from

<original>

by the skill, what changed, and that it's safe to edit or regenerate. The generated file is best-effort — still climb the Phase 5 ladder (validate → build → deploy) to confirm the stack actually comes up.

Example: Level 1 fragment (dev-only, single service)

yaml

dev:
  myapp:                        # service name from pyproject.toml [project] name
    image: okteto/python:3.12   # pyproject.toml declares requires-python >=3.12
    command: bash               # no FastAPI/Flask signal — shell is the safe default
    sync:
      - .:/usr/src/app          # full-repo sync; exclude .venv, __pycache__ if they grow

将

okteto.yaml

写入仓库根目录。用户必须看到实际文件内容，而非仅摘要。

每个草稿必须包含的内容：

头部注释块——第3.1节的说明，加上文件由
```
okteto-onboarding
```
生成、用户可编辑的提示。包含选定的范围层级及一行理由。
build:
部分（Level 2+）——每个服务对应一个条目，包含
```
context
```
和
```
dockerfile
```
。预构建镜像无需在此处添加（直接添加到
```
dev.<svc>.image
```
）。
deploy:
部分（Level 2+）——指向选定的部署源：
- Compose：
```
deploy: { compose: docker-compose.yml }
```
  （可选择指定
```
services:
```
  子集）。当仓库无Chart或清单文件时，这是最简单的方式。
- Helm：
```
helm upgrade --install
```
  命令，通过
```
--set ...=${OKTETO_BUILD_<SERVICE>_IMAGE}
```
  传递构建好的镜像（见“关联构建镜像”部分）。
- k8s清单：
```
kubectl apply -f ...
```
  命令。
详见下方示例。
dev:
部分（必选）——每个用户需要进入开发模式的服务对应一个条目，包含
```
image
```
、
```
command
```
和
```
sync
```
。键名必须与Okteto将部署的工作负载名称匹配：
- Compose仓库：compose服务名称（见第2.2节映射表）。
- Helm/k8s仓库（无compose）：Chart/清单文件创建的Kubernetes工作负载名称——即
```
Deployment
```
  /
```
StatefulSet
```
  的
```
metadata.name
```
  （渲染Chart或读取清单文件获取）。如果
```
dev:
```
  键名与已部署工作负载不匹配，将无法关联。
无论仓库结构如何，
```
image
```
、
```
command
```
和
```
sync
```
均来自Dockerfile+语言清单文件（见第2.3-2.4节）。
test:
部分（Level 3）——每个探测到的测试命令对应一个条目。详见下方示例。

同步路径默认值：

单服务仓库（根目录有一个Dockerfile或一个语言清单文件）：
```
.:/usr/src/app
```
是合理的默认值。如果Dockerfile设置了
```
WORKDIR
```
，则使用该路径作为右侧路径，而非
```
/usr/src/app
```
。
多服务仓库（按服务划分的Dockerfile或包含多个服务的compose）：将每个服务的同步范围限定在其自身子目录，例如
```
./api:/usr/src/app
```
。将整个仓库同步到每个容器几乎总是错误的。

每个非显而易见的选择都需要添加行内注释（镜像选择、命令选择、同步路径、

forward:

端口）。镜像和命令选择默认属于非显而易见的选择——必须添加注释。

将构建镜像关联到
deploy:
和
dev:
。

build:

下定义的镜像会推送到Okteto Registry，并通过环境变量暴露给清单文件的其他部分：

```
OKTETO_BUILD_<SERVICE>_IMAGE
```
——完整镜像引用（通常是你需要的）

OKTETO_BUILD_<SERVICE>_REGISTRY

_REPOSITORY

_SHA

——镜像各部分（如有需要）

<SERVICE>

是

build:

键名的大写形式，

替换为

（例如

build.web-api

→

OKTETO_BUILD_WEB_API_IMAGE

）。使用这些变量可确保部署的工作负载运行最新构建的镜像，而非过时或硬编码的镜像：

Helm：

--set api.image=${OKTETO_BUILD_API_IMAGE}

k8s清单：在
```
kubectl apply
```
前替换值（例如使用
```
envsubst
```
），或对镜像字段进行模板化。
Compose：
```
build:
```
部分已通过服务名称覆盖对应的compose
```
image:
```
——无需
```
--set
```
。
dev:
：当用户希望基于构建的应用镜像而非通用工具链镜像进行开发时，设置
```
dev.<svc>.image: ${OKTETO_BUILD_<SVC>_IMAGE}
```
（见第2.3节）。

示例：Level 2/3片段（build + deploy + dev + test）

yaml

build:
  api:
    context: ./api
    dockerfile: Dockerfile  # using the existing Dockerfile

deploy:
  - name: Deploy chart
    command: helm upgrade --install myapp ./chart --set api.image=${OKTETO_BUILD_API_IMAGE}  # built api image wired in

dev:
  api:
    image: okteto/golang:1.23  # tag from api/go.mod (go 1.23)
    command: bash               # Go services usually want a shell to `go run` manually
    sync:
      - ./api:/usr/src/app      # per-service sync; tighten if you have large generated dirs

test:
  api:
    image: okteto/golang:1.23
    context: ./api
    commands:
      - go test ./...           # detected from the project's test layout

示例：Level 2片段（compose驱动部署，无Chart）

yaml

build:
  api:
    context: ./api
    dockerfile: Dockerfile

deploy:
  compose: docker-compose.yml   # deploy the stack straight from compose — no chart or k8s manifests needed

dev:
  api:
    image: okteto/golang:1.23   # tag from api/go.mod (go 1.23)
    command: bash
    sync:
      - ./api:/usr/src/app

Compose作为部署源的注意事项。为本地开发编写的compose文件通常无法直接部署到集群。在确定使用

deploy: compose:

前，请扫描compose文件并向用户警告以下问题：

主机IP端口绑定（例如
```
127.0.0.1:9229:9229
```
）——Okteto的compose部署会拒绝此类配置（
```
Host IP is not allowed
```
）。请移除主机IP前缀（改为
```
9229:9229
```
）。仅用于调试的端口（例如调试器）可直接移除；这些端口应放在
```
dev.<svc>.forward
```
中。
源码绑定挂载卷（例如
```
./api:/usr/local/app
```
）——在集群中，这些卷会变成空卷，覆盖镜像中的应用代码，导致服务崩溃（例如
```
can't open file 'app.py'
```
）。这些内容应放在
```
dev.<svc>.sync
```
中，而非部署用的compose文件。

如果compose文件依赖这些仅适用于开发的结构，请提前告知用户——不要等到部署时才发现。按优先级处理：

生成可部署的compose文件——从原始文件派生
```
compose.okteto.yaml
```
，移除对集群不友好的部分，并将
```
deploy: compose:
```
指向该文件。详见“生成可部署的compose文件”部分。
复用现有部署用compose文件——如果仓库已包含此类文件（例如
```
*.preview*
```
或无开发卷/端口的生产环境compose），将
```
deploy: compose:
```
指向该文件。
使用Chart/k8s清单文件进行
```
deploy:
```
（如果仓库存在）。这就是为什么同时包含compose和Chart的仓库通常选择Chart作为
```
deploy:
```
数据源，而compose驱动
```
dev:
```
的原因（见第2.5节）。

生成可部署的compose文件（
compose.okteto.yaml
）。当compose是选定的部署源但文件包含仅适用于开发的结构时，请创建一个派生副本，而非编辑用户的原始文件。这是对用户文件的机械转换——并非手动编写的部署工件，因此需向用户展示与源文件的差异。明确引用该文件：

deploy: { compose: compose.okteto.yaml }

。应用以下转换：

移除主机IP端口前缀——
```
127.0.0.1:9229:9229
```
→
```
9229:9229
```
。仅用于调试的端口可直接移除；这些端口应放在
```
dev.<svc>.forward
```
中。
移除源码绑定挂载卷——例如
```
./src:/app
```
等。镜像已包含代码；这些内容应放在
```
dev.<svc>.sync
```
中。保留命名/数据卷（例如
```
db-data
```
）。
替换开发容器占位符——
```
entrypoint
```
/
```
command
```
为
```
sleep infinity
```
的服务在部署时无法运行应用。恢复其真实启动命令（来自Dockerfile的
```
CMD
```
或生产环境compose），或移除该覆盖配置。

有两类问题无法通过转换自动修复——需向用户标记这些问题，而非假装结果可用：

主机路径配置/脚本挂载（例如将初始化脚本挂载为容器的entrypoint）——移除挂载无法使服务正常运行；文件必须打包到镜像中。保留该配置并发出警告。
扫描无法推理的其他服务特定问题。

为

compose.okteto.yaml

添加头部注释：说明它由

<original>

文件派生，修改了哪些内容，以及可编辑或重新生成。生成的文件是最佳尝试结果——仍需通过第五阶段的验证流程（验证→构建→部署）确认栈是否能正常启动。

示例：Level 1片段（仅开发模式，单服务）

yaml

dev:
  myapp:                        # service name from pyproject.toml [project] name
    image: okteto/python:3.12   # pyproject.toml declares requires-python >=3.12
    command: bash               # no FastAPI/Flask signal — shell is the safe default
    sync:
      - .:/usr/src/app          # full-repo sync; exclude .venv, __pycache__ if they grow

4.2 Refine (Phase 4)

4.2 优化（第四阶段）

Show the file to the user. In collaborative mode, ask:

"Here's the draft. Want me to change anything before we validate? Common edits: adjust sync paths to exclude
node_modules
/
vendor
/
target
, change the dev image version, add an env var, or swap the deploy command."

Common edit patterns:

User says	Edit
"exclude `node_modules` "	Change `sync` to a list with `!node_modules` ignore patterns or use a more specific path
"use Go 1.21 instead"	Update `image:` to `okteto/golang:1.21`
"I need this env var"	Add to `dev.<svc>.environment:`
"use my values file"	Update `deploy:` helm command with `-f values.staging.yaml`

Iteration is cheap — keep editing until the user is satisfied. Do not move to Phase 5 until they say "looks good" or equivalent.

In autonomous mode, skip the ask and move directly to Phase 5. Edits will be requested via the PR review.

向用户展示文件。在协作模式下，询问：

"这是草稿文件。在验证前需要我修改什么吗？常见修改：调整同步路径以排除
node_modules
/
vendor
/
target
，更改开发镜像版本，添加环境变量，或更换部署命令。"

常见修改场景：

用户需求	修改内容
"排除 `node_modules` "	将 `sync` 改为包含 `!node_modules` 忽略模式的列表，或使用更具体的路径
"使用Go 1.21版本"	将 `image:` 更新为 `okteto/golang:1.21`
"我需要这个环境变量"	添加到 `dev.<svc>.environment:`
"使用我的values文件"	更新 `deploy:` 的Helm命令，添加 `-f values.staging.yaml`

迭代成本很低——持续修改直到用户满意。在用户确认“看起来没问题”或类似反馈前，请勿进入第五阶段。

在自主模式下，跳过询问直接进入第五阶段。修改请求将通过PR评审提出。

5. Phase 5 — Validate (tiered)

5. 第五阶段：分层验证

Climb the validation ladder as far as the environment supports. Tier 1 is mandatory; Tiers 2 and 3 are opt-in.

根据环境支持程度逐步完成验证流程。Tier 1为必填项；Tier 2和Tier 3为可选项。

5.1 Tier 1 —

okteto validate

(always)

5.1 Tier 1 —

okteto validate

（必选）

Run:

bash

okteto validate

What it catches: YAML syntax, schema violations, missing required fields. What it does NOT catch: wrong sync paths, missing services in

deploy:

, broken Helm refs, images that fail to build.

If it fails, treat as a Phase 4 issue and fix before continuing.

The skill does not finish without Tier 1 passing.

执行命令：

bash

okteto validate

可检测问题： YAML语法错误、 schema违反、缺失必填字段。 不可检测问题： 错误的同步路径、

deploy:

中缺失服务、无效的Helm引用、构建失败的镜像。

如果验证失败，将其视为第四阶段的问题并修复后再继续。

未通过Tier 1验证的情况下，技能不得结束。

5.2 Tier 2 —

okteto build

(offered if Dockerfiles or

build:

exist)

5.2 Tier 2 —

okteto build

（当存在Dockerfile或

build:

部分时提供）

Pre-check: run

okteto context show

. If it errors or returns no context, skip Tier 2 and inform the user:

"Skipping the build check — no Okteto context. The manifest is syntactically valid but I haven't proven the Dockerfiles build."

Otherwise, ask:

"I can run
okteto build
to prove every Dockerfile resolves and pushes. This takes a few minutes per service. Skip / build one service / build all?"

Default to build all. If the user has many services (≥ 4) and is in a hurry, offer narrowing.

Run:

bash

okteto build

bash

okteto build <service>

预检查：执行

okteto context show

。如果命令报错或未返回上下文，跳过Tier 2并告知用户：

"跳过构建检查——无Okteto上下文。清单文件语法有效，但尚未验证Dockerfile是否可构建。"

否则，询问用户：

"我可以执行
okteto build
来验证每个Dockerfile是否可解析并推送。每个服务需要几分钟时间。是否跳过/构建单个服务/构建所有服务？"

默认选择构建所有服务。如果用户有多个服务（≥4）且时间紧张，可提供缩小范围的选项。

执行命令：

bash

okteto build

或

bash

okteto build <service>

5.3 Tier 3 —

okteto deploy --wait

(offered if Tier 2 passed and user has a context)

5.3 Tier 3 —

okteto deploy --wait

（当Tier 2通过且用户有上下文时提供）

Note: there is no
okteto deploy --dry-run
flag. Full deploy is the only Tier 3 option.

Ask:

"I can do a full deploy to verify the manifest works end-to-end. This will create resources in your namespace
<ns>
. After it succeeds, I'll show you the endpoints. You can
okteto destroy
after if you want. Proceed?"

Run:

bash

okteto deploy --wait
okteto endpoints

On success: print endpoints. Do not run

okteto destroy

automatically — that's the user's call.

注意：**没有

okteto deploy --dry-run

**选项。完整部署是Tier 3的唯一验证方式。

询问用户：

"我可以执行完整部署以验证清单文件是否端到端可用。这将在你的命名空间
<ns>
中创建资源。部署成功后，我会展示端点信息。你可在之后执行
okteto destroy
清理资源。是否继续？"

执行命令：

bash

okteto deploy --wait
okteto endpoints

部署成功后： 打印端点信息。请勿自动执行
okteto destroy
——这是用户的选择。

5.4 On failure at any tier

5.4 任意Tier验证失败时的处理

Surface the raw CLI error verbatim. Do not paraphrase.
Diagnose the likely cause based on the manifest section involved (e.g., a Helm error →
```
deploy:
```
; a build error →
```
build:
```
or the Dockerfile).
Propose a concrete edit to the manifest. Show the diff, not "you should change X."
After the user approves the fix:
- If the edit changed manifest structure (added/removed/renamed sections, changed YAML shape), re-run Tier 1 first to catch new schema problems, then re-run the failing tier.
- If the edit was purely a value change (image version, sync path, env var), re-run only the failing tier.

直接展示原始CLI错误信息。请勿 paraphrase。
根据涉及的清单文件部分诊断可能原因（例如Helm错误→
```
deploy:
```
；构建错误→
```
build:
```
或Dockerfile）。
提出具体的清单文件修改建议。展示差异，而非仅说“你应该修改X”。
用户批准修复后：
- 如果修改改变了清单文件结构（添加/删除/重命名部分，更改YAML格式），请先重新运行Tier 1以检测新的schema问题，再重新运行失败的Tier。
- 如果仅修改了值（镜像版本、同步路径、环境变量），请仅重新运行失败的Tier。

5.5 Final summary

5.5 最终总结

Once the ladder is climbed (or stopped), summarize:

"✅
okteto validate
passed ✅
okteto build
passed for all services ⏭️
okteto deploy
skipped (you opted out) Next: run
/dev-setup
or invoke the
okteto
skill to deploy and start developing."

If tiers were skipped due to environment (no context), say so:

"⚠️ Skipped Tiers 2 and 3 (no Okteto context). The manifest is syntactically valid but not deploy-tested."

完成验证流程（或中途停止）后，总结结果：

"✅
okteto validate
验证通过 ✅
okteto build
所有服务构建通过 ⏭️
okteto deploy
已跳过（你选择不执行）下一步：执行
/dev-setup
或调用
okteto
技能进行部署并启动开发。"

如果因环境原因（无上下文）跳过了某些Tier，请说明：

"⚠️ 已跳过Tier 2和Tier 3（无Okteto上下文）。清单文件语法有效，但尚未经过部署测试。"

6. Phase 6 — Handoff or PR

6. 第六阶段：交接或创建PR

6.1 Collaborative mode: handoff

6.1 协作模式：交接

Point the user at the next step:

"The manifest is in place. To bring up your environment, you can:
Run
/dev-setup
for a guided deploy + dev mode
Or invoke the
okteto
skill in any future session — it'll pick up the manifest you just created
If you change the manifest, re-run
okteto validate
(or come back to me)."

State which validation tiers were run and which were skipped (see Section 5.5).

Do NOT delete the manifest, run
okteto destroy
, or push to a remote. The work product is the file on disk.

告知用户下一步操作：

"清单文件已创建完成。要启动你的环境，你可以：
执行
/dev-setup
进行引导式部署+开发模式
或在未来会话中调用
okteto
技能——它会自动识别你刚刚创建的清单文件
如果你修改了清单文件，请重新执行
okteto validate
（或再次联系我）。"

说明已执行的验证Tier和跳过的Tier（见第5.5节）。

请勿删除清单文件、执行
okteto destroy
或推送到远程仓库。工作成果是本地磁盘上的文件。

6.2 Autonomous mode: PR

6.2 自主模式：创建PR

Create a branch, commit the manifest, push, and open a PR. The PR is the human review gate.

Before running the commands below, substitute every
<placeholder>
with a real value from your Phase 1 / Phase 5 results. Do not send literal

<list>

<N>

<bulleted list of services...>

, etc. to a real PR. For the validation checklist, use

[x]

if the tier passed and

[ ]

if it was skipped or failed.

bash

git checkout -b okteto/onboarding
git add okteto.yaml
git commit -m "Add Okteto manifest

Generated by okteto-onboarding skill.
Discovered services: <list>
Scope level: <N>
Validation: <tiers passed>"
git push -u origin okteto/onboarding
gh pr create --title "Add Okteto manifest" --body "$(cat <<'EOF'

创建分支、提交清单文件、推送并打开PR。PR是人工评审的入口。

执行以下命令前，请将所有
<placeholder>
替换为第一/第五阶段的真实结果。请勿将字面

<list>

、

<N>

、

<bulleted list of services...>

等内容发送到真实PR中。对于验证 checklist，已通过的Tier标记为

[x]

，跳过或失败的标记为

[ ]

。

bash

git checkout -b okteto/onboarding
git add okteto.yaml
git commit -m "Add Okteto manifest

Generated by okteto-onboarding skill.
Discovered services: <list>
Scope level: <N>
Validation: <tiers passed>"
git push -u origin okteto/onboarding
gh pr create --title "Add Okteto manifest" --body "$(cat <<'EOF'

Summary

This PR adds an Okteto manifest generated by the

okteto-onboarding

skill.

This PR adds an Okteto manifest generated by the

okteto-onboarding

skill.

Discovered services

Scope level

Level <N> — <one-sentence rationale>

Validation

[<x or space>]
```
okteto validate
```
passed
[<x or space>]
```
okteto build
```
ran for all services
[<x or space>]
```
okteto deploy --wait
```
succeeded with endpoints

[<x or space>]
```
okteto validate
```
passed
[<x or space>]
```
okteto build
```
ran for all services
[<x or space>]
```
okteto deploy --wait
```
succeeded with endpoints

Decisions to confirm

Dev image picks (e.g.,
```
okteto/golang:1.22
```
) match your toolchain
Sync paths exclude appropriate generated dirs (node_modules, vendor, target)
Helm/kubectl deploy command matches your usual workflow

🤖 Generated by the okteto-onboarding skill EOF )"


The skill **never merges** the PR. A human reviews and merges.

Dev image picks (e.g.,
```
okteto/golang:1.22
```
) match your toolchain
Sync paths exclude appropriate generated dirs (node_modules, vendor, target)
Helm/kubectl deploy command matches your usual workflow

🤖 Generated by the okteto-onboarding skill EOF )"


**技能绝不会合并PR**。需由人工评审并合并。

7. Operating modes

7. 运行模式

7.1 Collaborative (default)

7.1 协作模式（默认）

A user is in the loop. Each phase that needs a decision asks a question. Defaults are presented but not auto-selected.

用户全程参与。每个需要决策的阶段都会询问用户。会展示默认选项但不会自动选择。

7.2 Autonomous (opt-in)

7.2 自主模式（可选）

No human is expected to intervene. Inferred from context the same way the existing

okteto

skill does — for example, when invoked from a CI pipeline or a ticket-driven session.

In autonomous mode:

Scope level → highest level the discovery supports. Level 2 requires a deploy source (a chart, k8s manifests, or a deployable compose file); Level 3 additionally requires detected tests. With no deploy source at all, stay at Level 1 even if tests are present. When both compose and a chart exist, pick the most conservative deploy source and note the choice in the PR.
Validation tier → Tier 1 always; Tier 2 if
```
okteto context show
```
succeeds; Tier 3 only if the trigger explicitly authorizes a deploy (label, env var, or explicit instruction).
Discovery ambiguities → pick the most conservative interpretation and note it in the PR description.
Phase 6 → always opens a PR (Section 6.2), never hands off.

无需人工干预。与现有

okteto

技能的判断方式一致——例如从CI流水线或工单驱动的会话中调用时。

在自主模式下：

范围层级 → 选择探测结果支持的最高层级。Level 2需要部署源（Chart、k8s清单或可部署的compose文件）；Level 3还需要探测到测试用例。如果无部署源，即使存在测试用例也保持Level 1。当同时存在compose和Chart时，选择最保守的部署源并在PR中注明该选择。
验证Tier → 始终执行Tier 1；如果
```
okteto context show
```
成功则执行Tier 2；仅当触发条件明确授权部署（标签、环境变量或明确指令）时才执行Tier 3。
探测歧义 → 选择最保守的解释并在PR描述中注明。
第六阶段 → 始终创建PR（见第6.2节），绝不进行交接。

8. CLI quick reference

8. CLI快速参考

Command	When	Purpose
`okteto validate`	Phase 5 Tier 1 (always)	Check manifest syntax/schema
`okteto context show`	Phase 5 pre-checks	Verify cluster connection before Tiers 2/3
`okteto build [<service>]`	Phase 5 Tier 2	Prove Dockerfiles resolve and push
`okteto deploy --wait`	Phase 5 Tier 3	Full end-to-end validation
`okteto endpoints`	Phase 5 Tier 3	Print URLs after a successful deploy

Never run

okteto up

from this skill — it's interactive and belongs to the existing

okteto

skill / the user. Never run

okteto destroy

— leave that to the user.

命令	使用场景	用途
`okteto validate`	第五阶段Tier 1（必选）	检查清单文件语法/schema
`okteto context show`	第五阶段预检查	在执行Tier 2/3前验证集群连接
`okteto build [<service>]`	第五阶段Tier 2	验证Dockerfile是否可解析并推送
`okteto deploy --wait`	第五阶段Tier 3	完整端到端验证
`okteto endpoints`	第五阶段Tier 3	部署成功后打印URL

请勿从本技能中执行

okteto up

——该命令是交互式的，属于现有

okteto

技能/用户的操作范畴。请勿执行

okteto destroy

——请留给用户操作。

9. Common mistakes to avoid

9. 需避免的常见错误

Triggering when an
okteto.yaml
already exists. Always do the pre-flight check from Section 1.
Generating a Helm chart or k8s manifests. This skill does not author deploy artifacts. If the user has no chart, no k8s manifests, and no deployable compose file, recommend Level 1 and stop. A compose file alone is enough for Level 2 via
```
deploy: compose:
```
— don't drop to Level 1 just because there's no chart. (The one exception is a derived
```
compose.okteto.yaml
```
— a mechanical transform of the user's own compose, Section 4.1 — never a chart or k8s manifest written from scratch.)
Assuming the chart drives
deploy:
when a compose file is also present. Ask which the user wants (Section 2.5); don't silently pick the chart.
Recommending
deploy: compose:
without scanning for dev-only constructs. Host-IP port bindings and source bind-mount volumes break a cluster deploy (Section 4.1 caveats). Warn the user up front, don't surface it at deploy time.
Reading only the root
docker-compose.yml
. Projects often keep the dev compose under
```
docker/
```
or as
```
*.dev.yml
```
, separate from a published-images root compose. Glob for all compose files and follow
```
include:
```
(Section 2.1). Building
```
dev:
```
from a published-images compose produces a useless manifest.
Putting every compose service in
dev:
. Backing services (databases, caches, object stores, brokers) are deploy-only infrastructure.
```
dev:
```
is for the services you edit (Section 2.2).
Copying a
sleep infinity
entrypoint into
dev.<svc>.command
. That's a dev-container placeholder, not a real command — use
```
bash
```
(Section 2.4).
Hard-coding a dev-image version. Read the version the repo declares (Section 2.3); only fall back to a default when none is declared, and flag the fallback.
Forgetting to wire built images downstream. A
```
build:
```
entry isn't enough on its own for Helm/k8s deploys — pass
```
${OKTETO_BUILD_<SERVICE>_IMAGE}
```
into the deploy command so the workload runs the image you just built.
Skipping the framing block. The
```
dev:
```
vs
```
deploy:
```
framing in Section 3.1 must be shown to the user and written into the manifest as a header comment.
Climbing the validation ladder without checking
okteto context show
first. Tiers 2 and 3 require a working context.
Paraphrasing CLI errors on validation failure. Show the raw output; the user (or the next agent) needs to see exactly what Okteto said.
Asking the user about everything. Trust the signals from Phase 1. Only ask when discovery is genuinely ambiguous.
Merging the PR in autonomous mode. The PR is the human gate. Never merge.
Recommending
okteto/samples/
templates. Those are demos. Build the manifest from discovered facts, not templates.

当
okteto.yaml
已存在时触发技能。始终执行第1节的预检查。
生成Helm Chart或k8s清单文件。本技能不负责编写部署工件。如果用户无Chart、无k8s清单且无可部署的compose文件，请推荐Level 1并停止。仅compose文件即可通过
```
deploy: compose:
```
达到Level 2——不要因为无Chart就降级到Level 1。（唯一例外是派生的
```
compose.okteto.yaml
```
——对用户自己的compose文件进行机械转换，见第4.1节——绝不从零开始编写Chart或k8s清单文件。）
当同时存在compose文件时默认选择Chart作为
deploy:
数据源。请询问用户的需求（见第2.5节）；请勿默认选择Chart。
未扫描仅适用于开发的结构就推荐
deploy: compose:
。主机IP端口绑定和源码绑定挂载卷会导致集群部署失败（见第4.1节注意事项）。请提前警告用户，不要等到部署时才发现。
仅读取根目录的
docker-compose.yml
。项目通常将开发环境compose放在
```
docker/
```
目录下或命名为
```
*.dev.yml
```
，与根目录的已发布镜像compose分离。请全局搜索所有compose文件并解析
```
include:
```
（见第2.1节）。基于已发布镜像compose构建的
```
dev:
```
部分是无用的清单文件。
将所有compose服务加入
dev:
。后台服务（数据库、缓存、对象存储、消息队列）仅用于部署。
```
dev:
```
仅用于需要编辑的服务（见第2.2节）。
将
sleep infinity
入口点复制到
dev.<svc>.command
。这是开发容器占位符，而非真实命令——请使用
```
bash
```
（见第2.4节）。
硬编码开发镜像版本。读取仓库声明的版本（见第2.3节）；仅当未声明版本时才使用默认值，并标记该默认值。
忘记将构建镜像关联到下游。仅添加
```
build:
```
条目不足以支持Helm/k8s部署——需将
```
${OKTETO_BUILD_<SERVICE>_IMAGE}
```
传递到部署命令中，确保工作负载运行刚刚构建的镜像。
跳过说明模块。第3.1节中
```
dev:
```
vs
```
deploy:
```
的说明必须展示给用户，并作为头部注释写入清单文件。
未检查
okteto context show
就开始验证流程。Tier 2和Tier 3需要可用的上下文。
验证失败时paraphrase CLI错误。展示原始输出；用户（或下一个agent）需要看到Okteto返回的准确信息。
询问用户所有问题。信任第一阶段探测到的信号。仅当探测结果确实存在歧义时才询问。
在自主模式下合并PR。PR是人工评审的入口。绝不自动合并。
推荐
okteto/samples/
模板。这些是演示模板。请基于探测到的事实构建清单文件，而非使用模板。",

okteto-onboarding

Original

Translation

Okteto Onboarding Skill

Okteto 入门技能

1. Activation

1. 触发条件

2. Phase 1 — Discover

2. 第一阶段：项目探测

2.1 Signal priority

2.1 信号优先级

2.2 Compose → Okteto mapping

2.2 Compose → Okteto 字段映射

2.3 Dev-image picks by language manifest

2.3 基于语言清单文件选择开发镜像

2.4 Dev-command picks

2.4 开发命令选择

2.5 When discovery is ambiguous

2.5 探测结果存在歧义时的处理

2.6 Output of Phase 1

2.6 第一阶段输出

3. Phase 2 — Negotiate scope

3. 第二阶段：协商范围

3.1 The framing block (always show this to the user)

3.1 说明模块（必须展示给用户）

3.2 The adaptive ladder

3.2 适配层级

3.3 Recommendation logic

3.3 推荐逻辑

3.4 Locking the level

3.4 锁定层级

4. Phases 3–4 — Draft and refine

4. 第三-四阶段：起草与优化

4.1 Draft (Phase 3)

4.1 起草（第三阶段）

4.2 Refine (Phase 4)

4.2 优化（第四阶段）

5. Phase 5 — Validate (tiered)

5. 第五阶段：分层验证

5.1 Tier 1 — okteto validate (always)

5.1 Tier 1 — okteto validate（必选）

5.2 Tier 2 — okteto build (offered if Dockerfiles or build: exist)

5.2 Tier 2 — okteto build（当存在Dockerfile或build:部分时提供）

5.3 Tier 3 — okteto deploy --wait (offered if Tier 2 passed and user has a context)

5.3 Tier 3 — okteto deploy --wait（当Tier 2通过且用户有上下文时提供）

5.4 On failure at any tier

5.4 任意Tier验证失败时的处理

5.5 Final summary

5.5 最终总结

6. Phase 6 — Handoff or PR

6. 第六阶段：交接或创建PR

6.1 Collaborative mode: handoff

6.1 协作模式：交接

6.2 Autonomous mode: PR

6.2 自主模式：创建PR

Summary

Summary

Discovered services

Discovered services

Scope level

Scope level

Validation

Validation

Decisions to confirm

Decisions to confirm

7. Operating modes

7. 运行模式

7.1 Collaborative (default)

7.1 协作模式（默认）

7.2 Autonomous (opt-in)

7.2 自主模式（可选）

8. CLI quick reference

8. CLI快速参考

9. Common mistakes to avoid

9. 需避免的常见错误

5.1 Tier 1 —
`okteto validate`
(always)

5.1 Tier 1 —
`okteto validate`
（必选）

5.2 Tier 2 —
`okteto build`
(offered if Dockerfiles or
`build:`
exist)

5.2 Tier 2 —
`okteto build`
（当存在Dockerfile或
`build:`
部分时提供）

5.3 Tier 3 —
`okteto deploy --wait`
(offered if Tier 2 passed and user has a context)

5.3 Tier 3 —
`okteto deploy --wait`
（当Tier 2通过且用户有上下文时提供）