netlify-agent-runner
Run AI agent tasks remotely on Netlify using Claude, Codex, or Gemini. Use when the user wants to run an AI agent on their site, get a second opinion from another model, or delegate development tasks to run remotely against their repo.
- Installs
- 2.4K
- Last 24h
- +19
- Trending rank
- #5975
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/netlify/context-and-tools --skill netlify-agent-runner- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads netlify-agent-runner automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Netlify Agent Runner
Run AI coding agents (Claude, Codex, Gemini) remotely on Netlify infrastructure to automate development tasks on your site.
Prerequisites
- The site must be linked to a Netlify project (via
netlify linkornetlify init). - Or skip linking entirely: pass
--project <name>(a project ID or name) directly tonetlify agents:createto target any Netlify site without linking first. - The Netlify CLI must be installed and authenticated
- Agent runs consume plan credits. If the account has no available credits — or the agent/AI usage limit has been reached —
netlify agents:createis blocked and the run won't start. That's an account/plan-state issue to surface to the user, not something to work around.
Use only documented CLI surfaces
Interact with agent tasks only through the documented netlify agents:* commands (plus netlify --help and the public CLI reference). Do not go around the CLI:
- Do not curl
https://api.netlify.com/...to fetch, create, or stop a task — the endpoint shapes are not part of the public contract. - Do not run
netlify api <method>as a recovery hatch when a documented command fails. - Do not read auth tokens out of
~/Library/Preferences/netlify/config.json(or anywhere on disk) to authenticate side-channel calls.
If a documented command fails, report the exact error and context to the user and stop — don't invent an undocumented way to reach the task.
How Agent Tasks Run
Read this before creating a task — agent tasks behave differently from running an agent locally, and the differences are easy to miss.
- Remote, not local. Tasks run on Netlify infrastructure, not on your machine. They operate on the site's connected repository, not your local working tree. The remote agent only sees what has been pushed to the remote — it cannot see uncommitted or unpushed changes.
- Branch-based. By default a task runs against the production branch (
mainormaster). To choose a different base branch for the agent to start from, use-b <branch>and make sure that branch has been pushed to the remote first, or the agent will be working from code that doesn't exist remotely.-bsets the base (starting) branch — not where the results are written (see the next bullet). - Output lands on a new branch — not in place. The agent does not commit its changes onto the base branch you selected. It pushes its work to a new branch with its own Deploy Preview, so your existing branch (or
main) is never overwritten. Review the task's results on that new branch / Deploy Preview — don't expect the base branch to change directly. - Asynchronous.
netlify agents:createreturns as soon as the task is queued — it does not block until the work is finished. When the command returns, the task is still running remotely. - No webhooks or callbacks. Nothing notifies you when a task changes state or completes. To find out what's happening, you have to poll with
netlify agents:show <task-id>ornetlify agents:list. - Statuses are terminal or not. A task moves through
new→running→ one ofdone,error, orcancelled. Keep polling until the status is one of those last three before you act on the results.
Typical workflow
- Create a task:
netlify agents:create "<prompt>" -a <agent>. Note the task ID it returns (use--jsonto capture it reliably). - Poll for status:
netlify agents:show <task-id>. Repeat periodically — there is no completion notification — until the status isdone,error, orcancelled. - Review the results once the task reaches
done(or inspect the failure onerror).
Creating Agent Tasks
# Run a prompt with the default agent
netlify agents:create "Add a contact form"
# Choose a specific agent: claude, codex, or gemini
netlify agents:create --prompt "Add dark mode" --agent claude
netlify agents:create -p "Update the README" -a codex
netlify agents:create -p "Write unit tests" -a gemini
# Target a specific branch
netlify agents:create -p "Fix the login bug" -a claude -b feature-branch
# Specify a project by name (if not in a linked directory)
netlify agents:create "Add tests" --project my-site-name
# Output result as JSON
netlify agents:create "Add a footer" --json
Options
| Flag | Description |
|---|---|
-a, --agent <agent> | Agent type: claude, codex, or gemini |
-p, --prompt <prompt> | The prompt for the agent to execute |
-b, --branch <branch> | Git branch to work on |
-m, --model <model> | Model to use for the agent |
--project <project> | Project ID or name |
--json | Output result as JSON |
Managing Agent Tasks
All netlify agents:* commands are project-scoped — they operate on a single project (the one your directory is linked to, or the one named with --project <name>), not on your whole team. netlify agents:list shows the tasks for that one project only; there is no team-wide command that lists tasks across all your sites. To see a different site's tasks, run from its linked directory or pass --project <name> for it.
List tasks
# List all tasks for the current site
netlify agents:list
# Filter by status
netlify agents:list --status running
netlify agents:list --status done
netlify agents:list --status error
# Output as JSON
netlify agents:list --json
Status values: new, running, done, error, cancelled.
Show task details
netlify agents:show <task-id>
netlify agents:show <task-id> --json
Stop a running task
netlify agents:stop <task-id>
Use Cases
Some of the many things you can do with Agent Runners:
| Category | Example prompt |
|---|---|
| Prototyping / internal tools | "Build an internal dashboard for our HR team" |
| Code reviews | "Audit the code with fresh eyes and identify areas for improvement" |
| Security audits | "Do a deep security audit of our codebase to identify any potential issues" |
| Feature suggestions | "Based on our current codebase & docs, what should we build next?" |
| Performance improvements | "Scan our codebase for performance bottlenecks and suggest improvements" |
| Telemetry & analytics | "What analytics things are we not tracking but probably should" |
| SEO audit | "Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text" |
| Copy improvements | "Rewrite our landing page copy to be more compelling and conversion-focused" |
| Accessibility | "Run an accessibility audit and fix all WCAG 2.1 AA violations" |
| Mobile responsiveness | "Improve the mobile responsiveness — audit every page on small viewports" |
| End-to-end tests | "Add end-to-end tests for our critical user flows using Playwright" |
| Unit tests | "Generate unit tests for our untested utility functions" |
| Documentation | "Generate a README and contributing guide based on our codebase" |
| Error handling | "Add proper error boundaries, logging, and user-friendly error states throughout the app" |
| UX polish | "Add loading states, skeleton screens, & transitions to improve perceived performance" |
| Form hardening | "Add form validation, rate limiting, and spam protection to our contact form" |
| Edge Functions | "Add an edge function for A/B testing on our landing page" |
Using as an Agent
If you are an AI agent, you can use netlify agents:create to delegate work to an agent running remotely on Netlify — for example, to get a second opinion from a different model.
IMPORTANT — ask for permission first, as a distinct confirmation step. Agent tasks run on Netlify infrastructure and cost the user credits, so a real approval gate matters. Get explicit permission before running any netlify agents:create command — and treat that as its own turn, separate from the user's original request. A directive-sounding prompt ("start a task…", "use the claude agent and pin it to Opus") is not itself the approval: it tells you what they want, but the billable command still waits for a yes.
Make the permission request a concrete proposal, not a menu:
- The exact command, filled in — e.g.
netlify agents:create -p "<the real prompt>" -a codex— not a<placeholder>and not a pick-one list of agents. - One agent, already chosen — commit to a single
-avalue and say why you picked it ("codex for a second opinion on the auth logic"), rather than offering claude/codex/gemini as interchangeable options. - Why, plus what happens after "yes": the run is asynchronous —
agents:createreturns as soon as the task is queued, there's no callback, and you'll pollnetlify agents:show <task-id>for the outcome. - Even if a prerequisite is missing (not authenticated, not linked to a site, not a git repo yet), still show the exact command and chosen agent you'll run once it's resolved — surface the blocker and the concrete proposal, rather than collapsing to only describing the blocker.
Never run these commands without the user's approval.
Before delegating, understand what you're handing off (see How Agent Tasks Run above):
- It runs remotely against the pushed branch — not your local work. The remote agent only sees code that has been committed and pushed. Do not delegate work that depends on your local, in-progress changes; the remote agent can't see them and will work from stale code. If a task needs your current changes, commit and push them first (or finish the work yourself).
- It's asynchronous — delegating does not block you. The task runs remotely while you keep working. But because there are no callbacks, you have to poll (
netlify agents:show <task-id>) to learn the outcome. Don't assume the task is done just because you delegated it — check the status before relying on or describing its results. - It's a separate, self-contained task — not a continuation of your session. The remote agent starts fresh from the repo and the prompt you give it. It has none of your conversation context, so write a complete, standalone prompt.
Useful for:
- Cross-validation — get a second opinion on your implementation from a different model
- Edge case discovery — another model may catch issues you missed
- Alternative approaches — see how a different model would solve the same problem
- Parallel work — kick off an independent task remotely while you continue on other work, then poll for its result
FAQ
What does the netlify-agent-runner skill do?
Run AI agent tasks remotely on Netlify using Claude, Codex, or Gemini. Use when the user wants to run an AI agent on their site, get a second opinion from another model, or delegate development tasks to run remotely against their repo.
How do I install netlify-agent-runner?
Run npx skills add https://github.com/netlify/context-and-tools --skill netlify-agent-runner in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/netlify-agent-runner/ (personal) or .claude/skills/netlify-agent-runner/ (project).
Which AI agents can use netlify-agent-runner?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is netlify-agent-runner safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains netlify-agent-runner?
It is published by netlify in netlify/context-and-tools. It has 2,436 recorded installs.
More from netlify/context-and-tools
netlify-deploy
netlify/context-and-tools
Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", "keep staging out of Google", or "add a deploy button to my README".
netlify-config
netlify/context-and-tools
Configure Netlify builds and routing via netlify.toml, redirects, and headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.
netlify-functions
netlify/context-and-tools
Write, configure, and deploy Netlify serverless functions in TypeScript, JavaScript, or Go. Use this when adding an API endpoint or backend route, adding a contact form handler, wiring auth or Identity signup/login hooks, identifying which Netlify user is calling a private or team-login-protected app, building streaming or AI-proxy responses, scheduling cron jobs, running long background jobs (batch processing/scraping), reacting to deploy or form events, setting up rate limiting or region/memory config, or reading environment variables and secrets inside a function. Covers file locations, the Request/Context/Response handler shape, path routing, config options, and local testing with netlify dev.
netlify-frameworks
netlify/context-and-tools
Deploy and configure web frameworks on Netlify — build settings and SSR/edge adapters plus local platform emulation and env vars. Use when setting up or fixing a framework deploy (Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / Eleventy / Vue / React), adding SSR or edge functions or middleware wired to Netlify context, fixing SPA redirect and catch-all rules, setting a build command or publish directory, or debugging "why isn't my env var updating" and framework build failures.
netlify-edge-functions
netlify/context-and-tools
Write, route, cache, and debug Netlify Edge Functions, the Deno-based TypeScript or JavaScript handlers in netlify/edge-functions that run at the network edge in front of static files and serverless functions. Activate this skill whenever someone wants to add auth middleware or a login gate, redirect or rewrite visitors by country or cookie, localize or personalize a page with geolocation, run A/B testing, transform or inject HTML into a response, stream server-side rendering at the edge, or cache an edge response. Also use it when an edge function silently does nothing, runs in the wrong order, ignores its Cache-Control headers, or cannot read an environment variable.
netlify-forms
netlify/context-and-tools
Serverless form handling on Netlify-hosted sites — detects HTML forms at deploy time, stores submissions, filters spam, and sends notifications. Use when adding a contact form, lead-capture form, file-upload form, or newsletter signup to a Netlify site; wiring AJAX form submission; setting up a custom thank-you page; adding a honeypot or reCAPTCHA to a form; getting forms working in Next.js, Nuxt, SvelteKit, Astro, or Gatsby; reading form submissions via the Netlify API; setting up submission notifications or ChatGPT automations on form submission events; or debugging missing submissions and forms that silently fail to register.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.