netlify-deploy

---
name: netlify-deploy
description: Link, configure, preview, and deploy web projects to Netlify with the Netlify CLI. Use when the user wants to publish a site, connect a repo, configure build settings, manage `netlify.toml`, or run preview and production deploys.
license: Apache-2.0
---

# Netlify Deployment Skill

Deploy web projects to Netlify using the Netlify CLI, with emphasis on safe previews, correct site linking, and accurate build configuration.

## Overview

This skill helps an agent:
- Verify Netlify CLI availability and authentication
- Inspect the project's framework, build command, and publish directory
- Link the local project to an existing Netlify site or create a new one
- Prefer preview deploys first, then promote to production when appropriate
- Adjust `netlify.toml` when configuration is missing or incorrect

## Prerequisites

- The current environment can run terminal commands.
- Netlify CLI is available, typically via `npx netlify`.
- The user can authenticate to Netlify.
- The working directory contains a deployable web project.

If Netlify CLI is missing or authentication is not ready, read [references/setup.md](references/setup.md) before continuing.

## Required Workflow

Follow these steps in order:

### Step 1: Inspect the project first

- Determine the framework and build shape before deploying.
- Inspect `package.json`, lockfiles, and `netlify.toml` if present.
- Identify the likely build command and publish directory.
- Confirm whether this is a static site, SPA, SSR app, monorepo app, or another pattern.

Use the bundled references only as needed:
- [CLI commands](references/cli-commands.md)
- [Deployment patterns](references/deployment-patterns.md)
- [netlify.toml guide](references/netlify-toml.md)

### Step 2: Verify Netlify tooling and authentication

Check whether Netlify CLI is available and whether the user is authenticated.

```bash
npx netlify --version
npx netlify status
```

If CLI access or authentication is missing, stop and use [references/setup.md](references/setup.md) instead of guessing.

### Step 3: Determine site link status

Use `npx netlify status` to determine whether the local directory is already linked to a site.

If it is not linked, prefer linking to an existing site before creating a new one. When the project is backed by Git, inspect the remote first:

```bash
git remote show origin
npx netlify link --git-remote-url <REMOTE_URL>
```

If that fails because no matching site exists, initialize a new site:

```bash
npx netlify init
```

### Step 4: Confirm build inputs before deploy

Before deploying, make sure the project can build locally. Install dependencies with the project's package manager if needed, then verify or refine the build command and publish directory.

```bash
npm install
```

If a `netlify.toml` file exists, inspect it. If it is missing or incorrect, create or update it only when needed.

### Step 5: Prefer preview deploys first

Unless the user explicitly asks for a production deploy or the task clearly requires one, start with a preview deploy:

```bash
npx netlify deploy
```

Use production deploys only when the target configuration is already understood and the user wants a live rollout:

```bash
npx netlify deploy --prod
```

If the environment blocks outbound network access, rerun with the host's elevated or unrestricted network mode when available.

### Step 6: Report the exact deployment result

Return:
- The deploy URL
- The production URL when relevant
- The detected or applied build settings
- Any configuration changes made
- Any follow-up actions still needed

## Error Handling

Common issues and solutions:

**"Not logged in"**
→ Run `npx netlify login` or use token-based auth

**"No site linked"**
→ Run `npx netlify link` or `npx netlify init`

**"Build failed"**
→ Check build command and publish directory in netlify.toml or CLI prompts
→ Verify dependencies are installed
→ Review build logs for specific errors

**"Publish directory not found"**
→ Verify build command ran successfully
→ Check publish directory path is correct

## Environment Variables

For secrets and configuration:

1. Never commit secrets to Git
2. Set in Netlify dashboard: Site Settings → Environment Variables
3. Access in builds via `process.env.VARIABLE_NAME`

## Tips

- Use `netlify deploy` (no `--prod`) first to test before production
- Run `netlify open` to view site in Netlify dashboard
- Run `netlify logs` to view function logs (if using Netlify Functions)
- Use `netlify dev` for local development with Netlify Functions

## External Docs

- Netlify CLI docs: https://docs.netlify.com/cli/get-started/
- netlify.toml reference: https://docs.netlify.com/configure-builds/file-based-configuration/