You ask your AI coding agent to scaffold a new SPFx web part. It opens a terminal, runs yo @microsoft/sharepoint, and then… nothing. The generator is sitting on an interactive arrow-key prompt, waiting for a human to press Enter, and your agent — which can write a thousand lines of TypeScript in ten seconds — is stuck staring at a menu it can’t navigate. You come back from getting coffee to find the session timed out.

Or maybe it didn’t hang. Maybe it finished the scaffold, ran npm install, and quietly pulled in an @microsoft/sp-webpart-base version that doesn’t match the rest of your solution, because it pattern-matched on some blog post from three SPFx major versions ago. Or it wrote you a perfectly reasonable-looking React component — using raw <div>s and inline styles instead of Fluent UI — because generic “build me a React card component” training data doesn’t know SharePoint has an opinion about that. Or it ran gulp bundle --ship on a project that migrated to Heft two sprints ago, and you spent twenty minutes wondering why the command wasn’t found.

None of this is because your AI agent is bad at coding. It’s because SharePoint Framework is a narrow, fast-moving, opinionated framework, and general-purpose training data treats it like generic React-plus-npm. The agent isn’t wrong about JavaScript. It’s wrong about SPFx specifically — the toolchain quirks, the non-interactive flags, the Fluent UI conventions, the data-access defaults that every experienced SPFx dev just knows.

There’s now an official fix for this, and it’s worth five minutes of your time today: SharePoint/spfx-dev-skills — a GitHub repo, maintained under the SharePoint org, that packages exactly this tribal knowledge into a set of “agent skills.” Install it, and your coding agent stops guessing and starts following the same rules a senior SPFx developer would enforce in code review.

This post is the opening of a five-part series walking through the entire skill pack. Today: what it is, why it exists, and the two rules inside it you should start following even if you never touch an AI agent again.

What “Agent Skills” Actually Means Here

If you haven’t used Claude Code, GitHub Copilot’s custom instructions, or a similar tool, “agent skill” might sound like marketing fluff. It isn’t complicated: a skill is just a structured markdown file that an AI coding agent reads before it acts, telling it which commands to run, in what order, with which flags, and which anti-patterns to avoid. It’s not a code library you npm install into your project — it’s a rulebook your agent consults, the same way a new hire on your team might consult an internal wiki page before touching the build pipeline for the first time.

The spfx-dev-skills README states the problem plainly, and it’s worth quoting directly because it’s exactly the pain described above:

“AI agents working from generic web context tend to mix toolchain versions, run interactive prompts that hang in a terminal, invent package versions” and skip validation.

That’s not a hypothetical risk — it’s a description of specific, observed agent failure modes: hanging terminals, invented versions, mixed toolchains, skipped validation. The skill pack exists to close each of those gaps with an explicit, checkable rule.

This is worth calling out clearly: this isn’t some rando’s gist. It lives under the SharePoint GitHub organization, ships under the MIT license, and takes contributions via normal pull requests against main (see its CONTRIBUTING.md). Treat it as you would any other piece of officially-adjacent SPFx tooling — worth adopting, worth watching for updates, worth contributing back to if you find a gap.

Anatomy of the Skill Pack

The repo is deliberately small and easy to read in one sitting. Strip away the license and contributing files, and the entire thing is one router plus four reference documents:

plugins/spfx/skills/spfx/
├── SKILL.md                — router: which reference to read for which task
└── references/
    ├── create.md            — scaffolding web parts, extensions, libraries, ACEs
    ├── upgrade.md            — version upgrades via CLI for Microsoft 365
    ├── react-design.md       — Fluent UI v9 rules ("Copilot UI Contract v2.1")
    └── pnpjs.md               — PnPjs as the default SharePoint/Graph data layer

SKILL.md is the entry point every agent reads first, and its job is purely navigational — it tells the agent which of the four reference files actually answers the task at hand:

This router pattern matters more than it looks. It means the skill pack doesn’t try to cram every SPFx rule into one giant document an agent has to parse in full for every task — it loads only the relevant slice. That’s also exactly how this blog series is structured: this post gives you the map, and posts two through five each spend a full article on one reference file, with real code samples pulled straight from the source.

The Four Pillars at a Glance

Here’s a one-paragraph teaser of each pillar, with the single rule from each file that most SPFx developers will find genuinely surprising or overdue.

Create (full post: Stop Letting AI Hang on yo @microsoft/sharepoint) — the fix for the hanging-terminal problem from the intro. The skill mandates non-interactive scaffolding with explicit flags (--skip-install --no-insight --framework react ...) instead of the default arrow-key wizard, plus a m365 spfx doctor environment check before scaffolding even starts, so Node/npm mismatches get caught before they cause a half-finished project.

Upgrade (full post: The Upgrade Playbook) — the standout rule here is procedural discipline: the skill refuses to let an agent start an upgrade unless the git working tree is clean first, because a version upgrade “rewrites many files” and you need a clean diff to review and a safe rollback point. That’s a rule plenty of human developers forget too.

React Design (full post: The 16 Rules Your AI Should Follow Before Writing Fluent UI) — this reference is the most detailed of the four: a 16-section normative contract (it literally calls itself “Copilot UI Contract v2.1”) governing everything from Fluent UI v9 component composition to container-context awareness (a web part embedded in a narrow zone must never assume full-page layout) to a hard “MUST NOT recreate Fluent components using custom HTML/CSS” rule.

PnPjs (full post: Why PnPjs Should Be Non-Negotiable) — the headline rule: “use PnPjs for every SharePoint and Microsoft Graph data operation in SPFx,” full stop, with raw SPHttpClient or MSGraphClientV3 reserved only for cases where PnPjs genuinely can’t be used. It also specifies how: initialize once in onInit(), not per-call, and use .select()/.top() to avoid over-fetching.

Two Universal Rules Worth Adopting Today

Two rules in SKILL.md apply no matter what task you’re doing, and they’re good enough that you should start following them by hand even before you install anything:

1. PnPjs is the default, not an option. The skill states this as an unconditional rule: “Use PnPjs by default for all SharePoint and Microsoft Graph data operations.” Falling back to SPHttpClient should be the exception that requires a reason, not the default habit some of us fell into years ago. If you’re still writing raw HTTP calls out of muscle memory, this is your nudge to stop — post five in this series shows exactly why.

2. Give npm install room to breathe. The skill specifies running npm install synchronously with a minimum three-minute timeout, explicitly because “SPFx’s extensive dependency structure” makes it slower than a typical npm project. This sounds trivial, but it’s the kind of detail that causes AI agents (and CI pipelines configured by humans in a hurry) to declare a build “failed” when it was actually just still installing. If your CI has an aggressive install timeout tuned for a lightweight frontend project, SPFx will blow right through it.

How to Actually Install It

The README lays out two installation paths, and it’s honest that one of them isn’t fully baked yet:

• Option A — Skills CLI (forthcoming): a dedicated CLI tool for installing skills is planned but not yet shipped as of this writing.
• Option B — manual install (works today): clone the repo and copy the plugins/spfx/skills/spfx/ folder directly into your coding agent’s skills directory. For Claude Code, that typically means dropping it under your project or user-level skills folder so it’s picked up automatically the next time you start a session.

That’s genuinely it — there’s no build step, no package to publish, no config file to write. It’s markdown files in a folder that your agent reads before it acts.

What’s Next

This post was the map. The next four go one level deeper into each reference file, with the actual source text, real before/after code comparisons, and the reasoning behind each rule:

• Post 2: Stop Letting AI Hang on yo @microsoft/sharepoint — Non-Interactive SPFx Scaffolding
• Post 3: The Upgrade Playbook — How AI Agents Should (and Shouldn’t) Touch Your SPFx Version
• Post 4: The 16 Rules Your AI Should Follow Before Writing One Line of Fluent UI
• Post 5: Why PnPjs Should Be Non-Negotiable in Every AI-Generated SPFx Web Part

If you use an AI coding agent for SPFx work at all — and at this point, most of us do, whether officially sanctioned or just quietly pasted into a chat window — install this skill pack before your next feature branch. Watch what your agent gets right on the first try that it used to get wrong on the third.

Source note: Every technical claim in this post is drawn directly from SharePoint/spfx-dev-skills — specifically its README.md and plugins/spfx/skills/spfx/SKILL.md — current as of this writing. The four reference files (create.md, upgrade.md, react-design.md, pnpjs.md) are covered in full depth in the rest of this series.