Okteto Manifest Optimizer

This skill reviews and rewrites Okteto Manifests (okteto.yaml) so they follow Okteto's documented performance best practices, together with the .dockerignore, .oktetoignore, and .stignore files that go with them. Slow environments almost always trace to one of three causes: unpinned images that defeat node cache reuse, a bloated build or sync context, or dependencies that are re-downloaded on every start. This skill removes those.

Full field reference, copy-paste ignore-file templates, and a worked manifest live in reference/okteto-manifest-fields.md, next to this file. Read it when you need the exact syntax; the rules here are enough to act.

Operating rules

These rules prevent the mistakes that make environments slow. Apply every one to every manifest you produce.

1. Verify against the repo — never invent. Read the Dockerfile(s), the dependency manifest (package.json, go.mod, pom.xml, requirements.txt), and the existing okteto.yaml first. Every service name, image, sync path, volume, and cache dir must trace to something in the repo.
2. Pin every image. Never :latest — use a version tag or an @sha256 digest. When a service has a build: entry, wire its dev container to it with ${OKTETO_BUILD_<NAME>_IMAGE} (uppercase the build name, - becomes _: build api → ${OKTETO_BUILD_API_IMAGE}, build web-dev → ${OKTETO_BUILD_WEB_DEV_IMAGE}). A dev container on a plain toolchain image (no build:) just pins that image.
3. Context and sync are the highest-impact levers — and the two ignore files read in opposite order. .dockerignore: * first, then !-include only build inputs (Docker applies the last matching rule). .stignore: !-include the active source first, then * (Syncthing applies the first matching rule; * first syncs nothing). Never sync artifacts, dependency directories, or .git. Add a .oktetoignore when the deploy or test context is large.
4. Persist dependencies and caches — don't re-fetch them. Put dependency and build-cache directories in dev.<svc>.volumes, mirror them in test.<name>.caches for test containers, and use BuildKit cache mounts in the Dockerfile. See the per-language cache map.
5. Always set resources.requests and resources.limits on dev containers. Both are unset by default, which starves the scheduler and causes slow or Pending starts.
6. Get forward vs reverse direction right. forward is localPort:remotePort (reach a container port from localhost). reverse is remotePort:localPort (send from the container back to your machine, e.g. a debugger callback). Swapping them silently breaks the connection.
7. Order the Dockerfile by change frequency and never COPY . .. Base image and system packages first, dependency install next, source copy last. Copy only what each stage needs. This is what makes Okteto Smart Builds and layer caching effective.
8. Validate and rebuild what you changed — without being asked. okteto.yaml, the Dockerfile, and .dockerignore are build inputs: nothing syncs them, so the environment is stale until it is rebuilt. As soon as the manifest is written, run okteto validate (it works offline). Then rebuild and redeploy the way the okteto skill requires — okteto build <service> and okteto deploy --wait — and report the outcome: endpoints on success, the error and your fix on failure. Never run okteto up; it is interactive and would hang.