docs(tutorial): getting started with AI coding agents

[ekline]

Context

This tutorial addresses the highest-value gap found by a tutorial and how-to coverage review that combined competitor analysis (8 competitors), persona needs, and a feature-coverage audit of src/content/ and src/tutorials/.

Top 3 gaps

Rank	Priority	Gap	Source	Personas served	Proposed guide type
1	High	No hands-on tutorial for using AI coding agents with Okteto environments. The Agentic Workflows section has four explanation/reference pages but no guided walkthrough.	Competitor analysis + feature audit	Developer, new user	Tutorial
2	High	No single guide for connecting a local IDE (VS Code, JetBrains, Cursor) to a Development Container. Coverage is a reference/ssh-server.mdx page plus remote-debugging steps buried inside seven per-language File Sync guides.	Competitor analysis	Developer	How-to
3	Medium	No rollout guide for a platform team taking a team from install to developers working. Pieces exist (Admin Dashboard, RBAC, Catalog, Agent Skills Rollout) but no single path connects them.	Persona needs + competitor analysis	Administrator	How-to

What this PR adds

src/tutorials/ai-coding-agents.mdx — an eight-step tutorial that takes a developer from zero to a working agent loop on the Movies sample application: install the plugin, deploy with /dev-setup, add an endpoint via the agent in an okteto up session verified with okteto exec, run the e2e suite with okteto test, sweep health with /debug-env, isolate a parallel run with -n <ns>, and clean up.

Serves the developer persona (primary) and new user persona (secondary). Registered in sidebarTutorials.js after the Preview Environments tutorial, and it uses the claude.svg card logo that was added in #1293 but never wired to a tutorial.

Also included

src/content/agentic/index.mdx describes the plugin as "two skills and one slash command". Upstream okteto/okteto-agent-skills is at v1.3.0 and ships four skills (okteto, okteto-onboarding, okteto-debugging, okteto-preview) and two commands (/dev-setup, /debug-env). Verified against the repo's plugins/okteto/ tree and README.

The new tutorial documents the real inventory, so leaving the landing page stale would put two pages in direct contradiction. This PR corrects the inventory table and the two sentences that state the counts, and adds a link to the new tutorial from Next steps. Scoped strictly to that contradiction — happy to split it out if you'd rather land it separately.

Research sources

• Competitors covering AI agents in remote/ephemeral environments: Coder (an entire top-level "Run AI Coding Agents in Coder" section), Ona/ex-Gitpod (Agents + Automations + Guardrails), Signadot (four closed-loop agent tutorials for Claude Code, Cursor, and Codex), Qovery ("Deploy with AI Agent" and "Agent Skills" quickstarts). Orca, Paseo, and herdr are agent-orchestration tools whose docs all teach "run agents on a remote machine" — none teach ephemeral, per-task, isolated environments with a lifecycle, which is the Okteto wedge.
• Feature audit: the July 2026 repositioning around agentic development (Reposition docs around agentic development to match okteto.com #1291) shipped explanation pages only; no tutorial followed.
• Gap 2 evidence: Coder maintains a 14-page IDE access tree and Ona a dedicated Editors section; Okteto has no equivalent entry point.

How to verify

1. cd docs && yarn && yarn start, then open http://localhost:8080/tutorials/ai-coding-agents
2. Confirm the tutorial appears in the Tutorials sidebar and that its card on /tutorials renders the Claude logo
3. Run yarn build to validate links and anchors — this was not run in authoring because Node was unavailable in the environment; all seven internal links were instead resolved by hand against target frontmatter and sidebars.js
4. Walk the tutorial end to end against a real Okteto instance. Every command, file path, service name, and test assertion was verified against okteto/movies, okteto/okteto CLI source, and okteto/okteto-agent-skills @ v1.3.0, but the flow has not been executed end to end.

Not verified

• No screenshots. Existing tutorials lean on images; this one is text and code only, since capturing accurate UI was not possible here. Worth a follow-up pass if you want visual parity.
• Steps 2–6 assume Claude Code, because the slash commands and guardrail hooks are exclusive to its plugin. A note points other agents at npx skills add.

ekline[bot] <202747777+ekline[bot]@users.noreply.github.com>

---

📝 Created with EkLine · View session

[netlify]

✅ Deploy Preview for okteto-docs ready!

Name	Link
🔨 Latest commit	9cea78b
🔍 Latest deploy log	https://app.netlify.com/projects/okteto-docs/deploys/6a8583a3fc1801000803b455
😎 Deploy Preview	https://deploy-preview-1331--okteto-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.