Update to Netlify

{
  "description": "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.",
  "included_files": [],
  "name": "netlify-agent-runner",
  "skill_md_contents": "---\nname: netlify-agent-runner\ndescription: 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.\n---\n\n# Netlify Agent Runner\n\nRun AI coding agents (Claude, Codex, Gemini) remotely on Netlify infrastructure to automate development tasks on your site.\n\n## Prerequisites\n\n- The site must be **linked to a Netlify project** (via `netlify link` or `netlify init`).\n- **Or skip linking entirely:** pass `--project <name>` (a project ID or name) directly to `netlify agents:create` to target any Netlify site without linking first.\n- The Netlify CLI must be installed and authenticated\n- Agent runs **consume plan credits**. If the account has no available credits — or the agent/AI usage limit has been reached — `netlify agents:create` is **blocked** and the run won't start. That's an account/plan-state issue to surface to the user, not something to work around.\n\n## Use only documented CLI surfaces\n\nInteract with agent tasks only through the documented `netlify agents:*` commands (plus `netlify --help` and the public CLI reference). Do **not** go around the CLI:\n\n- **Do not curl `https://api.netlify.com/...`** to fetch, create, or stop a task — the endpoint shapes are not part of the public contract.\n- **Do not run `netlify api <method>`** as a recovery hatch when a documented command fails.\n- **Do not read auth tokens** out of `~/Library/Preferences/netlify/config.json` (or anywhere on disk) to authenticate side-channel calls.\n\nIf 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.\n\n## How Agent Tasks Run\n\nRead this before creating a task — agent tasks behave differently from running an agent locally, and the differences are easy to miss.\n\n- **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.\n- **Branch-based.** By default a task runs against the production branch (`main` or `master`). 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. `-b` sets the base (starting) branch — not where the results are written (see the next bullet).\n- **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.\n- **Asynchronous.** `netlify agents:create` returns 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.\n- **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>` or `netlify agents:list`.\n- **Statuses are terminal or not.** A task moves through `new` → `running` → one of `done`, `error`, or `cancelled`. Keep polling until the status is one of those last three before you act on the results.\n\n### Typical workflow\n\n1. **Create** a task: `netlify agents:create \"<prompt>\" -a <agent>`. Note the task ID it returns (use `--json` to capture it reliably).\n2. **Poll** for status: `netlify agents:show <task-id>`. Repeat periodically — there is no completion notification — until the status is `done`, `error`, or `cancelled`.\n3. **Review** the results once the task reaches `done` (or inspect the failure on `error`).\n\n## Creating Agent Tasks\n\n```bash\n# Run a prompt with the default agent\nnetlify agents:create \"Add a contact form\"\n\n# Choose a specific agent: claude, codex, or gemini\nnetlify agents:create --prompt \"Add dark mode\" --agent claude\nnetlify agents:create -p \"Update the README\" -a codex\nnetlify agents:create -p \"Write unit tests\" -a gemini\n\n# Target a specific branch\nnetlify agents:create -p \"Fix the login bug\" -a claude -b feature-branch\n\n# Specify a project by name (if not in a linked directory)\nnetlify agents:create \"Add tests\" --project my-site-name\n\n# Output result as JSON\nnetlify agents:create \"Add a footer\" --json\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `-a, --agent <agent>` | Agent type: `claude`, `codex`, or `gemini` |\n| `-p, --prompt <prompt>` | The prompt for the agent to execute |\n| `-b, --branch <branch>` | Git branch to work on |\n| `-m, --model <model>` | Model to use for the agent |\n| `--project <project>` | Project ID or name |\n| `--json` | Output result as JSON |\n\n## Managing Agent Tasks\n\nAll `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.\n\n### List tasks\n\n```bash\n# List all tasks for the current site\nnetlify agents:list\n\n# Filter by status\nnetlify agents:list --status running\nnetlify agents:list --status done\nnetlify agents:list --status error\n\n# Output as JSON\nnetlify agents:list --json\n```\n\nStatus values: `new`, `running`, `done`, `error`, `cancelled`.\n\n### Show task details\n\n```bash\nnetlify agents:show <task-id>\nnetlify agents:show <task-id> --json\n```\n\n### Stop a running task\n\n```bash\nnetlify agents:stop <task-id>\n```\n\n## Use Cases\n\nSome of the many things you can do with Agent Runners:\n\n| Category | Example prompt |\n|----------|---------------|\n| Prototyping / internal tools | \"Build an internal dashboard for our HR team\" |\n| Code reviews | \"Audit the code with fresh eyes and identify areas for improvement\" |\n| Security audits | \"Do a deep security audit of our codebase to identify any potential issues\" |\n| Feature suggestions | \"Based on our current codebase & docs, what should we build next?\" |\n| Performance improvements | \"Scan our codebase for performance bottlenecks and suggest improvements\" |\n| Telemetry & analytics | \"What analytics things are we not tracking but probably should\" |\n| SEO audit | \"Audit our site for SEO issues — missing meta tags, broken links, slow pages, missing alt text\" |\n| Copy improvements | \"Rewrite our landing page copy to be more compelling and conversion-focused\" |\n| Accessibility | \"Run an accessibility audit and fix all WCAG 2.1 AA violations\" |\n| Mobile responsiveness | \"Improve the mobile responsiveness — audit every page on small viewports\" |\n| End-to-end tests | \"Add end-to-end tests for our critical user flows using Playwright\" |\n| Unit tests | \"Generate unit tests for our untested utility functions\" |\n| Documentation | \"Generate a README and contributing guide based on our codebase\" |\n| Error handling | \"Add proper error boundaries, logging, and user-friendly error states throughout the app\" |\n| UX polish | \"Add loading states, skeleton screens, & transitions to improve perceived performance\" |\n| Form hardening | \"Add form validation, rate limiting, and spam protection to our contact form\" |\n| Edge Functions | \"Add an edge function for A/B testing on our landing page\" |\n\n## Using as an Agent\n\nIf 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.\n\n**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.\n\nMake the permission request a concrete proposal, not a menu:\n\n- **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.\n- **One agent, already chosen** — commit to a single `-a` value and say why you picked it (\"codex for a second opinion on the auth logic\"), rather than offering claude/codex/gemini as interchangeable options.\n- **Why**, plus **what happens after \"yes\"**: the run is asynchronous — `agents:create` returns as soon as the task is queued, there's no callback, and you'll poll `netlify agents:show <task-id>` for the outcome.\n- **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.\n\nNever run these commands without the user's approval.\n\nBefore delegating, understand what you're handing off (see [How Agent Tasks Run](#how-agent-tasks-run) above):\n\n- **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).\n- **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.\n- **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.\n\nUseful for:\n\n- **Cross-validation** — get a second opinion on your implementation from a different model\n- **Edge case discovery** — another model may catch issues you missed\n- **Alternative approaches** — see how a different model would solve the same problem\n- **Parallel work** — kick off an independent task remotely while you continue on other work, then poll for its result\n"
}