Preface¶

After finishing a frontend project, you often have to go through a familiar yet tedious deployment workflow: log into the hosting platform, link the site, confirm the build command and publish directory, first create a preview deployment before pushing to production. The commands themselves are not complex, but there are many steps and it’s easy to miss something. Especially when using an AI programming assistant to modify code, if the assistant is unfamiliar with Netlify CLI conventions, you may get stuck on authentication, unlinked sites, or confuse preview deployments with official releases.

netlify-deploy is exactly the Agent Skill designed for these scenarios. It固化 “Check login → Link or create a site → Install dependencies → Preview/Production Deployment” into a reusable process guide, allowing tools that support the Agent Skills standard (such as Cursor, Codex, Claude Code) to follow a consistent set of steps when you mention deployment, hosting, or publishing to Netlify, instead of piecing together commands on the fly.

What is this¶

netlify-deploy is a curated Skill收录 in the skills/.curated/ directory of the openai/skills repository by OpenAI. Its official path is:

https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy

Its positioning is clear: use the Netlify CLI (the documentation and examples uniformly use npx netlify, no need to install it globally) to complete the deployment, hosting and release of Web projects, covering both preview deployments and production deployments. Trigger scenarios include the user saying “deploy to Netlify”, “publish the site”, “link an existing site”, etc.

It should be noted that the repository’s README has indicated that the overall project is deprecated, and subsequent Codex-related examples are more recommended to refer to openai/plugins; but as of the writing of this article, the SKILL.md and supporting references/ of netlify-deploy can still be obtained from the aforementioned curated path. The Skill is based on the universal SKILL.md format (see Agent Skills Open Standard), so the same skill package can be placed in the skills directory corresponding to different AI programming tools for use.

Core Features and Highlights¶

According to the official SKILL.md, this Skill mainly automates the following tasks:

1. Verify Netlify CLI login status
   First run npx netlify status. If not logged in, guide the user to execute npx netlify login (browser OAuth); you can also use the environment variable NETLIFY_AUTH_TOKEN (generate a Personal Access Token in Netlify user settings).

2. Check if the project is already linked to a site
   Determine whether the current directory has been linked to a Netlify site from the output of status. If already linked, proceed directly to deployment; if not linked, try to link according to the Git remote URL, or go through the new site creation process.

3. Link an existing site or create a new site
   - When there is a Git remote: npx netlify link --git-remote-url <REMOTE_URL>
   - If the link fails or the site does not exist: npx netlify init (select team, site name, build configuration, generate netlify.toml if necessary)

4. Check dependencies before deployment
   Run npm install for npm projects; if yarn/pnpm are detected, use the corresponding installation command.

5. Distinguish between preview and production deployments
   - For existing sites, default test: npx netlify deploy (Draft/Preview, get an independent preview URL)
   - For new sites or explicit production release: npx netlify deploy --prod
   The CLI will read netlify.toml, or interactively ask for the build command / publish directory; the Skill will also try to infer the framework default values based on package.json.

6. Result feedback and troubleshooting guidance
   After deployment, you should report the Deploy URL, production site URL (if --prod was used), console log entry to the user, and prompt netlify open. Common errors (not logged in, unlinked site, build failure, non-existent publish directory) have corresponding handling suggestions in the Skill.

The Skill directory also includes on-demand reference documents: references/cli-commands.md, references/deployment-patterns.md, references/netlify-toml.md, which are used to supplement command quick references, scenario decision trees and configuration instructions, avoiding stuffing all details into the main SKILL.md.

Installation and Activation¶

Obtain the Skill files¶

Get the netlify-deploy folder from the official directory (at least include SKILL.md, it is recommended to keep references/ as well):

# Clone the repository and copy the curated skill directory (choose one of the acquisition methods)
git clone https://github.com/openai/skills.git
cp -r openai/skills/skills/.curated/netlify-deploy <your-skills-directory>/netlify-deploy

In Codex, you can also use the built-in installer to install curated skills according to the openai/skills documentation (if not recognized after installation, restart Codex):

$skill-installer netlify-deploy

Place in the skills directory of each tool¶

Agent Skills are “one directory + one SKILL.md”. Different tools have different scanning paths, and you can place them according to the official documentation (both project-level and user-level are available):

Directory structure example:

netlify-deploy/
├── SKILL.md
└── references/
    ├── cli-commands.md
    ├── deployment-patterns.md
    └── netlify-toml.md

The Cursor documentation also states that for compatibility, it will additionally load paths such as .claude/skills/, .codex/skills/. When collaborating across tools, prioritizing .agents/skills/ is often more convenient.

Preconditions for runtime¶

The Skill itself does not replace the Netlify account and network permissions. Before use, you need to meet:

• The local machine has a Node.js environment available to execute npx netlify ... (Netlify official CLI documentation requires Node.js 18.14.0 or higher; the Skill calls via npx, and does not enforce global npm install -g netlify-cli)
• Logged in to Netlify, or the NETLIFY_AUTH_TOKEN environment variable has been set
• The current directory is a valid Web project
• If the sandbox blocks outbound network, the Skill prompts that you need to retry with higher permissions (documented as sandbox_permissions=require_escalated); deployment may take several minutes, please pay attention to the timeout setting

Typical Usage Examples¶

The following process comes from the complete example in the official SKILL.md, which can be executed locally or let the Agent follow the steps.

1. Authentication¶

npx netlify status

# If not logged in:
npx netlify login

# When there is no browser environment, you can use Token:
export NETLIFY_AUTH_TOKEN=your_token_here

The Token can be generated at https://app.netlify.com/user/applications#personal-access-tokens. This is consistent with the authentication method in the Netlify official CLI documentation.

2. Link or initialize the site¶

git remote show origin
npx netlify link --git-remote-url https://github.com/user/repo

# If the site does not exist yet:
npx netlify init

3. Install dependencies and deploy¶

npm install

# First create a preview (Draft Deploy)
npx netlify deploy

# Confirm there are no issues before deploying to production
npx netlify deploy --prod

4. Build configuration (netlify.toml)¶

If there is already a netlify.toml in the repository root directory, the CLI will use it automatically. If not, the CLI will ask for the build command and publish directory. Common default value examples given by the Skill include:

• Next.js: npm run build, publish directory .next
• React (Vite): npm run build, publish directory dist
• Pure static HTML: no build command required, publish the current directory

The actual project should still be based on the local build artifact directory. For example, Vite can also explicitly specify the directory:

npx netlify deploy --dir=dist --prod

Regarding the choice of deployment mode, the Skill’s decision tree recommends: New sites or first launch tend to use --prod; for existing sites when modifying code, first run deploy for preview, then use --prod.

5. What to say to the Agent after enabling the Skill¶

After enabling the Skill, you don’t need to memorize the commands, just describe your intention directly, for example:

• “Deploy the current Vite project to Netlify, first generate a preview link”
• “Link the existing Netlify site using the Git remote and perform a production release”
• “This repository has not created a site yet, help me run netlify init and then --prod“

The Agent should follow the Skill to first check status, handle login and linking, and then deploy, instead of skipping authentication and directly running deploy.

Applicable Scenarios and Notes¶

Most suitable for:

• Static sites, Vite/React, simple frontend projects for individuals or small teams, hoping to “get a preview URL right after modification”
• When using an AI assistant to write pages, hand over the “launch” process to the same conversation闭环 (translation note: keep “closed-loop” for technical consistency)
• Need to unify team deployment话术 (translation note: keep “verbiage” for technical consistency) and steps (preview first, keys not committed to Git, install dependencies first)

Notes when using:

1. Preview first, then production release: The Skill clearly recommends that for most existing sites, first run deploy without --prod, confirm the preview URL before officially releasing.
2. Do not commit secrets to the repository: Environment variables should be placed in the Netlify console (Site Settings → Environment Variables) or use npx netlify env:set, and read them via process.env in the build.
3. If the build fails, reproduce it locally: For issues such as non-existent publish directory, exit code 1, first run npm run build locally to check the output directory and netlify.toml.
4. Network and sandbox: If deployment fails in a restricted sandbox, follow the Skill’s prompt to apply for relaxed network permissions before trying again.
5. Repository status: Pay attention to the deprecated notice in the README of openai/skills when referencing it; if your tool ecosystem has migrated to plugin distribution, follow the current tool’s documentation for installation, and the Skill content shall prevail based on SKILL.md.
6. Framework exceptions: The optimal build configuration for different frameworks on Netlify may evolve with the platform; the default values in the Skill are guidance suggestions, and complex projects (especially Next.js, etc.) should double-check against Netlify Framework Documentation and CLI Getting Started.

After deployment, you can use npx netlify open to open the console. If you are using Netlify Functions, you can use npx netlify logs to view function logs; use npx netlify dev to debug Functions locally.

Summary¶

netlify-deploy turns the Netlify CLI deployment workflow into a standard executable process for Agents: login verification, site linking, dependency installation, separation of preview and production deployments, and附带 (translation note: keep “includes” for technical consistency) command and scenario references. For developers who often push frontend demos to Netlify, it makes up for the steps that are most likely to be missed by the assistant in the “write and deploy” closed-loop.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/netlify-deploy

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