Here’s the exact moment your AI agent gets stuck. It runs:

yo @microsoft/sharepoint

And the generator responds with an interactive wizard:

? Which type of client-side component to create? (Use arrow keys)
❯ WebPart
  Extension
  Library
  Adaptive Card Extension

To a human, this is trivial — press the down arrow, hit Enter, move on. To an AI coding agent driving a terminal, this is a wall. There’s no arrow key to send, no visual menu to read, no way to “see” which option is highlighted. Some agents will guess-type a number and get it wrong. Others will just… wait. Forever, or until your session times out.

This is post two of the SPFx Dev Skills series — post one introduced SharePoint/spfx-dev-skills, the official skill pack that fixes exactly this kind of AI-agent failure. Today we go deep on the fix for scaffolding specifically: the create.md reference, which replaces the interactive wizard with a fully flag-based, non-interactive command. Even if you never touch an AI agent, this is worth adopting by hand — it’s simply a faster, more repeatable way to scaffold.

Step Zero: Is the Environment Even Ready?

Before scaffolding anything, the skill insists on checking whether the toolchain is actually installed and healthy. Skipping this step is exactly how you end up debugging a scaffold failure that was actually a Node version mismatch three layers down.

First, confirm the CLI for Microsoft 365 is installed:

m365 version

If that command isn’t found, install it globally:

npm install -g @pnp/cli-microsoft365@latest --silent --no-fund --no-audit

Then run the environment doctor:

m365 spfx doctor

This single command verifies Node version, npm version, and other prerequisites against what the current (or target) SPFx version actually supports. If Node is incompatible, the skill’s guidance is specific: check whether a version manager — fnm or nvm — is available, and try switching to a compatible Node version.

Here’s the detail most people miss, agent or human: each Node version has its own set of globally installed packages. Switch Node versions with fnm or nvm, and tools you had installed a minute ago — including the CLI for Microsoft 365 itself — may simply not be there anymore under the new version. The skill’s rule is explicit: re-run m365 spfx doctor after switching Node versions, don’t assume the switch alone fixed things.

If doctor reports missing packages — commonly yo or @microsoft/generator-sharepoint — install them globally the same quiet way:

npm install -g <package> --silent --no-fund --no-audit

And if none of that resolves it — no version manager available, no compatible Node version installed, or some other error persists — the skill has a hard stop built in: stop and tell the user what needs fixing before proceeding. This is worth calling out as good engineering discipline on its own. An agent (or a script, or a junior dev under deadline pressure) that keeps retrying a broken environment instead of surfacing the actual blocker wastes everyone’s time. Fail loud, fail early, fail with a specific reason.

The Non-Interactive Scaffold Command

Once the environment checks out, here’s the command that replaces the interactive wizard entirely — for a React web part:

yo @microsoft/sharepoint --solution-name "<name>" --framework react --component-type webpart --component-name "<WebPartName>" --skip-install --no-insight

Every flag here answers a question the wizard would otherwise ask interactively:

• --solution-name — the solution folder/name (wizard’s first prompt)
• --component-type webpart — skips the WebPart/Extension/Library/ACE menu shown above
• --framework react — skips the framework selection prompt
• --component-name — the actual web part’s display name
• --skip-install — don’t run npm install as part of the generator; do it as an explicit, separate, monitorable step (see next section)
• --no-insight — opt out of the generator’s usage-data collection prompt, which is itself an interactive yes/no that would otherwise block

Scaffolding an extension instead of a web part follows the same non-interactive pattern, just with different flags — note --extension-type replaces the framework selection, and --framework none is used since extensions don’t render through a framework the same way:

yo @microsoft/sharepoint --solution-name "<name>" --component-type extension --extension-type ApplicationCustomizer --component-name "<Name>" --framework none --skip-install --no-insight

The skill is blunt about why this matters: “always use non-interactive mode with explicit flags… Interactive mode (arrow-key navigation) is unreliable in agent terminals and causes wrong template selection.” That last part is the sneaky failure mode — it’s not just hangs. An agent that does manage to send a keystroke to an interactive prompt can easily select the wrong menu item, and you won’t notice until you’re staring at a Library project when you asked for a WebPart.

There’s exactly one sanctioned escape hatch in this reference: if a user explicitly needs the legacy gulp toolchain, opt in via --use-gulp on the generator. Notice the framing — this is an explicit, deliberate choice, not a fallback an agent should reach for on its own. Left to its own devices, the skill defaults toward the modern Heft toolchain (more on that distinction in a moment).

Installing Dependencies Without Getting Flagged as “Stuck”

Since scaffolding used --skip-install, dependencies get installed as their own explicit step:

npm install --silent --no-fund --no-audit

Run from the generated project directory. The three flags here aren’t cosmetic — they’re about producing output an agent (or a CI log) can actually parse without noise: --silent suppresses the progress spam, --no-fund skips the “please fund this package” nags, and --no-audit skips the post-install vulnerability audit report cluttering the output with information that isn’t the point of this step.

This connects directly to a rule from post one worth repeating here because it bites people at exactly this step: run npm install with a minimum three-minute timeout. SPFx’s dependency tree is large — larger than a typical lightweight frontend project — and a CI pipeline or agent harness configured with an aggressive default timeout will declare this step “failed” when it was really just still working.

Packaging for Deployment: Two Toolchains, One Rule

When it’s time to produce a deployable package, the command you run depends entirely on which toolchain the project uses — and the skill is explicit that you check this rather than assume it:

Determine this from .yo-rc.json or the @microsoft/sp-* versions in package.json before running anything. Then:

Heft (v1.22+):

heft build --production
heft package-solution --production

gulp (≤ v1.21.1):

gulp bundle --ship
gulp package-solution --ship

Either path produces the deployable .sppkg in sharepoint/solution, ready to upload to your App Catalog. Getting this toolchain check wrong is exactly the “mixes gulp commands into a Heft project” failure mode from post one’s opening — the fix is simply: check first, don’t guess.

What’s Next

This post covered create.md end to end — environment checks, non-interactive scaffolding, dependency install discipline, and toolchain-aware packaging. Next in the series: The Upgrade Playbook — how the skill pack governs version upgrades, and why it refuses to even start one on a dirty git working tree.

If you scaffold SPFx projects with an AI agent today, try swapping in the exact commands above on your next new component. If you scaffold by hand, they’re worth adopting anyway — a scaffold that never waits on a prompt is a scaffold you can script, automate, and repeat without babysitting it.

Source note: Every command and rule in this post is quoted or closely paraphrased from SharePoint/spfx-dev-skills, specifically plugins/spfx/skills/spfx/references/create.md, current as of this writing.