netlify-deploy

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 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:

Step 2: Verify Netlify tooling and authentication

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

npx netlify --version
npx netlify status

If CLI access or authentication is missing, stop and use 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:

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

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

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.

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:

npx netlify deploy

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

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:

Never commit secrets to Git
Set in Netlify dashboard: Site Settings → Environment Variables
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/