Skip to content

docs(tutorial): getting started with AI coding agents #1331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ekline wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(tutorial): getting started with AI coding agents #1331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions sidebarTutorials.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ module.exports = {
items: [
'getting-started-with-okteto',
'preview-environments',
'ai-coding-agents',
'aws-lambda',
'compose-getting-started',
'external-resources',
Expand Down
10 changes: 7 additions & 3 deletions src/content/agentic/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,25 +49,28 @@ This pre-installs the marketplace and the plugin for every developer and keeps b

## Installing in other agents

The skills are built on the open [Agent Skills](https://agentskills.io) format, so the same `okteto` and `okteto-onboarding` skills run in Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, and other compatible agents. Install them with the [`skills` CLI](https://github.com/vercel-labs/skills), which detects your agent and installs into it:
The skills use the open [Agent Skills](https://agentskills.io) format, so the same `okteto`, `okteto-onboarding`, `okteto-debugging`, and `okteto-preview` skills run in Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI, and other compatible agents. Install them with the [`skills` CLI](https://github.com/vercel-labs/skills), which detects your agent and installs into it:

```bash
npx skills add okteto/okteto-agent-skills
```

Agents that read a plain instruction file can use the tool-neutral `AGENTS.md` (or, for GitHub Copilot, `.github/copilot-instructions.md`) from the [plugin repository](https://github.com/okteto/okteto-agent-skills) instead. These load the full guidance on every turn rather than on demand.

The `/dev-setup` command ships only with the Claude Code plugin. Every other method carries the two skills.
The `/dev-setup` and `/debug-env` commands ship only with the Claude Code plugin. Every other method carries the four skills.

## Skills and commands

The plugin installs two skills and one slash command:
The plugin installs four skills and two slash commands:

| | What it does | When it activates |
|---|---|---|
| `okteto` skill | Teaches the agent the Okteto CLI: deploying with `okteto deploy`, building with `okteto build`, running tests with `okteto test`, reading services from `okteto.yaml`, and the commands it must never run (like `okteto up`). | The project has an `okteto.yaml`, or you mention Okteto. |
| `okteto-onboarding` skill | Discovers your services from Docker Compose files, Helm charts, Kubernetes manifests, or Dockerfiles; drafts an `okteto.yaml`; and validates it with `okteto validate`, `okteto build`, and `okteto deploy`. | The project has no `okteto.yaml` and you ask to set it up for Okteto. |
| `okteto-debugging` skill | Triages a broken environment with a playbook per failure mode: `CrashLoopBackOff`, `OOMKilled`, `ImagePullBackOff`, `Pending`, runtime errors, deploy failures, and file sync issues. Diagnostics are read-only. | You describe an unhealthy service, or paste output showing one. |
| `okteto-preview` skill | Deploys a Preview Environment for a branch or pull request with `okteto preview deploy`, captures its endpoints, and posts the URL back. Also covers wiring previews into GitHub Actions or GitLab CI/CD. | You ask for a shareable environment or URL for a branch or pull request. |
| `/dev-setup` command | Validates the manifest, runs `okteto deploy --wait`, prints the environment URLs, and guides you into a dev session on the service you pick. | You run it. |
| `/debug-env` command | Runs a read-only health sweep of the environment and reports a root cause and fix for each unhealthy service. Pass a service name to scope it to one. | You run it. |

## Skill activation

Expand Down Expand Up @@ -114,6 +117,7 @@ In both modes the agent follows the same [command rules](agentic/best-practices.

## Next steps

- [Getting started with AI coding agents](/docs/tutorials/ai-coding-agents) — a hands-on walkthrough on the Movies sample application
- [Collaborative Workflows](agentic/collaborative-workflows.mdx) — work alongside your agent
- [Autonomous Workflows](agentic/autonomous-workflows.mdx) — let the agent handle it end to end
- [Best Practices](agentic/best-practices.mdx) — command rules, common pitfalls, and troubleshooting
184 changes: 184 additions & 0 deletions src/tutorials/ai-coding-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
---
title: Getting started with AI coding agents
description: Install the Okteto plugin for AI agents and use an agent to deploy, change, and test the Movies app
id: ai-coding-agents
sidebar_custom_props: { logo: "claude" }
---

AI coding agents produce better results when they can deploy code and run tests against real services instead of reasoning about files on your laptop. The [Okteto plugin for AI agents](https://github.com/okteto/okteto-agent-skills) teaches your agent the Okteto CLI: which commands to run, which it must never run, and how to discover your services from the Okteto Manifest.

In this tutorial, you install the plugin, bring up a Development Environment for the [Movies](https://github.com/okteto/movies) sample application, and work through one change with the agent: it adds an endpoint to a service, verifies it inside the running container, and runs the end-to-end test suite against the live environment. You then give a second agent run its own Namespace so parallel work never collides.

## Prerequisites

- Access to an Okteto instance. If you don't have one, follow the [installation guide](/docs/get-started/install/).
- The [Okteto CLI installed and configured](/docs/get-started/install-okteto-cli/) with your Okteto instance.
- [Claude Code](https://claude.com/product/claude-code) installed. Steps 2 through 6 use its plugin, which carries the slash commands. Step 7 works with any agent.
- A [GitHub](https://github.com) account.

## Step 1: Fork and clone the Movies app

Fork the [Movies](https://github.com/okteto/movies) repository to your own GitHub account, then clone your fork:

```console
git clone https://github.com/<your-username>/movies.git
cd movies
```

This microservices application has a React frontend, a Node.js `catalog` service, a Java `rent` service, Go `api` and `worker` services, and supporting infrastructure (MongoDB, Kafka, PostgreSQL).

The repository already contains an `okteto.yaml` that defines how to build, deploy, develop, and test every service. It also ships a `CLAUDE.md` describing the architecture and the per-service dev commands. The plugin you install next supplies the Okteto knowledge; `CLAUDE.md` supplies the project-specific knowledge.

## Step 2: Install the Okteto plugin

Run these two commands inside Claude Code:

```
/plugin marketplace add okteto/okteto-agent-skills
/plugin install okteto
```

The first command registers the repository as a plugin source. The second installs the plugin, which adds four skills and two slash commands:

| | What it does |
|---|---|
| `okteto` skill | Teaches the Okteto CLI: deploying, building, running tests, reading services from `okteto.yaml`, isolating worktrees, and the commands agents must never run. |
| `okteto-onboarding` skill | Drafts and validates an `okteto.yaml` for a project that has none. The Movies app already has one, so this skill stays idle. |
| `okteto-debugging` skill | Triages unhealthy environments, with a playbook per failure mode (`CrashLoopBackOff`, `OOMKilled`, `ImagePullBackOff`, `Pending`, sync issues). |
| `okteto-preview` skill | Deploys Preview Environments for a branch or pull request and posts the URL back. |
| `/dev-setup` command | Checks prerequisites, deploys the environment, prints the endpoints, and guides you into a dev session. |
| `/debug-env` command | Runs a read-only health sweep and reports a root cause and fix per unhealthy service. |

The plugin also installs guardrail hooks that enforce its two hardest rules mechanically rather than relying on the model to remember them. The hooks block `okteto up` outright, because it is interactive and hangs an agent's shell, and they require your confirmation before `okteto destroy`, `okteto preview destroy`, or `okteto namespace delete` runs.

:::note
The skills use the open [Agent Skills](https://agentskills.io) format, so `npx skills add okteto/okteto-agent-skills` installs the same four skills into Cursor, OpenAI Codex, GitHub Copilot, and other compatible agents. The slash commands and the guardrail hooks ship only with the Claude Code plugin.
:::

## Step 3: Deploy the environment

From the `movies` directory, ask Claude Code to bring up the environment:

```
/dev-setup
```

The agent confirms your CLI is installed and pointed at your Okteto instance, runs `okteto deploy --wait` to build every image and deploy every service, and then runs `okteto endpoints` to print the public URLs.

The first deployment builds six images, so expect it to take several minutes. When it finishes, the agent reports the endpoints and asks which service you want to work on.

Open the `movies` endpoint in your browser. You should see the Movies catalog with six films.

## Step 4: Add an endpoint with the agent

The agent cannot start a development session for you — `okteto up` is interactive, and the plugin's hooks deny it. Start it yourself, in your own terminal, from the `movies` directory:

```console
okteto up catalog
```

This puts the `catalog` service into development mode: Okteto syncs your local files into the Development Container and runs `yarn start`, which starts the service under `nodemon`. Leave this terminal running.

Now ask the agent for a change:

```
Add a GET /catalog/count endpoint to the catalog service that returns the
number of movies as JSON. Verify it inside the dev container with okteto exec.
```

The agent edits `catalog/server.js`. File sync copies the change into the Development Container within seconds, `nodemon` restarts the service, and the agent verifies the result without a rebuild:

```console
okteto exec -- curl -s localhost:8080/catalog/count
```

:::info
Run `okteto exec` from the same directory where you ran `okteto up`. It targets the Development Container for that directory's manifest, and fails when no development session is active.
:::

Because `catalog` is in development mode, its log output appears in your `okteto up catalog` terminal rather than in `okteto logs catalog`. This is the collaborative pattern: you own the session, the agent runs commands inside it with `okteto exec`, and neither of you waits on a build between iterations.

Verify the change yourself against the public endpoint. Get the URL from `okteto endpoints`, then request the new path:

```console
curl -s https://movies-<your-namespace>.<your-okteto-domain>/catalog/count
```

## Step 5: Run the end-to-end tests

The `okteto.yaml` defines an `e2e` test container that runs a Playwright suite against the live environment. Ask the agent to run it:

```
Run the e2e tests and tell me whether my change broke anything.
```

The agent runs the test container in the cluster:

```console
okteto test e2e
```

The suite checks that the frontend serves its title and that `/catalog` returns the six expected films. Your new endpoint adds a path rather than changing `/catalog`, so all tests should still pass. Test artifacts land in `tests/test-results` and `tests/playwright-report`.

This is the loop that makes agents useful on Okteto: change code, verify it in the running container, and run the real test suite against real services — with no local Kubernetes and no CI round trip.

## Step 6: Check environment health

Ask the agent for a read-only sweep of the environment:

```
/debug-env
```

The command reads `okteto.yaml` for the canonical service list, inspects pod state in your Namespace, and reports a root cause, the supporting evidence, and a proposed fix for each unhealthy service. It performs no writes: it never deploys, builds, or destroys anything, so it is safe to run against an environment you care about.

With a healthy environment it reports that every service is running. Scope it to one service by passing a name, as in `/debug-env catalog`.

## Step 7: Isolate a parallel agent run

Your active Namespace comes from the Okteto context, which is global to your machine rather than per-directory. Two agents working in two checkouts of the same repository deploy into the same Namespace and overwrite each other's environments, so `okteto endpoints` and `okteto logs` return the wrong data and one agent's teardown destroys the other's work.

Give each parallel run its own Namespace. Create it once:

```console
okteto namespace create movies-agent-2
```

Then pass `-n` on every command for that run:

```console
okteto deploy --wait -n movies-agent-2
okteto test e2e -n movies-agent-2
okteto endpoints -n movies-agent-2
```

Agents use the per-command `-n` flag rather than `okteto namespace use`, which switches the active Namespace in the shared global context and races with every other run on the machine. Namespace names are lowercase alphanumeric plus `-`, and start and end with an alphanumeric character.

## Step 8: Clean up

Exit development mode for `catalog` and restore its original deployment:

```console
okteto down catalog
```

Your environment keeps running, so you can pick up where you left off. When you no longer need it, tear it down:

```console
okteto destroy
okteto namespace delete movies-agent-2
```

:::warning
The plugin's hooks pause and ask for your confirmation before an agent runs either of these commands. Pipelines that own their own environments can pre-authorize teardown by setting `OKTETO_ALLOW_AGENT_DESTROY=1`.
:::

## Next steps

You installed the Okteto plugin, deployed a Development Environment through an agent, changed a service and verified it inside the running container, ran the end-to-end suite against live services, and isolated a parallel run in its own Namespace 🚀

- [Collaborative Workflows](/docs/agentic/collaborative-workflows/) goes deeper on the `okteto up` plus `okteto exec` pattern you used in Step 4
- [Autonomous Workflows](/docs/agentic/autonomous-workflows/) covers the ticket-to-pull-request loop, where the agent deploys, tests, and opens the pull request without you in the loop
- [Best Practices and Troubleshooting](/docs/agentic/best-practices/) lists every command an agent may and may not run, plus the reasoning behind each rule
- [Okteto Test](/docs/testing/getting-started-test/) explains how to define test containers for your own application
- [Getting started with Preview Environments](/docs/tutorials/preview-environments) wires the same test suite into a per-pull-request environment