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:

• CLI commands
• Deployment patterns
• netlify.toml guide

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:

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/