Status: Public Preview — behaviour may change.

What it does

A skill is a folder you attach to a declarative agent containing a required SKILL.md file, plus optional resource files and scripts. The agent loads a skill's contents into context only when a task needs it, so you can package a long, specific procedure without spending the agent's instruction budget on it. Add them through Agent Builder or the Microsoft 365 Agents Toolkit.

Key facts

• This replaces the older meaning of "skills" — the task descriptions people used to write inline in agent instructions. Same word, different thing. Instructions now reference skills rather than containing them.
• Eight skills per agent, either route. Maximum directory depth is three, and 350 files across all skills.
• Agent Builder takes a compressed .zip up to 50 MB with a 25 MB per-file cap. The Agents Toolkit takes a directory and will not take a .zip, but the whole app package is capped at 10 MB — a much tighter ceiling in practice.
• SKILL.md instructions must be under 20,000 characters. That's the escape hatch from the 8,000-character limit on declarative agent instructions themselves.
• Scripts allowed: .py, .js, .mjs, .cjs, .ts, .mts, .sh, .bash. Resource files cover the usual Office, PDF, image and structured-data types.
• The script sandbox has no network access at runtime and cannot install packages. It also can't call connectors, API plugins or MCP servers — those go through the orchestrator, not the sandbox.
• Sensitivity labels on skill files are retained and honoured, but user-defined permissions and Double Key Encryption are not supported. Uploaded files land in tenant-scoped SharePoint Embedded containers.
• Agents Toolkit requires declarative agent manifest version 1.9, and the feature is behind the TEAMSFX_AGENT_SKILLS environment variable.
• Agent Builder route needs a qualifying Copilot licence (or PAYG) and enrolment in the Microsoft Frontier Program.

When to use / skip

Use it when the same task comes up repeatedly and the output has to look the same every time — a standard report format, a review template, a data transform with branded output. The value is the script: model-generated code varies run to run, a bundled script doesn't. That repeatability is the actual selling point, not the context saving.

Skip it for one-off tasks, for anything that needs to call an API or the internet from a script, and for anything you expect to share across a fleet of agents — reuse across agents isn't supported at this stage of the preview, so every agent needs its own copy.

Configuration decisions

• Agent Builder or Agents Toolkit. Not a preference — the limits differ enough to decide the design. Anything with sizeable reference assets is Agent Builder territory; the Toolkit's 10 MB app package fills up fast.
• What goes in a script versus what goes in instructions. Deterministic transforms and formatting belong in scripts. Judgement belongs in SKILL.md. Getting this line wrong is why skills underperform.
• How many skills, and where the boundaries are. Eight is the ceiling and it arrives sooner than teams expect. Decompose by task, not by topic.
• Where the source of truth lives. Skill files are uploaded artefacts, not solution components. Decide now whether the canonical copy sits in a repo with the Toolkit project, or whether someone is going to hand-maintain a .zip.

Gotchas

• Skills and embedded files can't be combined yet. An agent that has both isn't supported. If the agent already has files attached, this isn't available to you today.
• The sandbox's no-network rule catches people who assume a script can fetch a currency rate or hit an internal API. It can't. If the data isn't in the package or reachable through the orchestrator, the skill can't get it.
• Preinstalled packages exist but aren't guaranteed. A script that imports something unconfirmed fails at runtime, not at upload.
• Upload the complete .zip in Agent Builder — a bare SKILL.md is rejected. Obvious once you've hit it, less so the first time.
• The Toolkit path needs a manifest bump to 1.9. Agents created with an older toolkit version will fail to add a skill until you update the manifest, and the error doesn't say so plainly.

Consultant notes

• The scoping conversation that goes wrong is "can we build a skills library for the organisation". Not yet. No reuse across agents in preview, and eight per agent, so the realistic unit of work is one agent with a handful of well-drawn skills — not a shared catalogue. Say that early or you'll be redesigning at build time.
• The Frontier Program prerequisite kills more pilots than the technical limits do. Confirm the tenant is enrolled before you put this in a statement of work; it isn't something the client's admin can just switch on.
• What surprises people in UAT is variance. Teams test a skill three times, get identical output, and assume determinism. The script is deterministic; the model deciding when to invoke the skill is not. Test the trigger phrasing as hard as you test the output.
• Treat skill files as governed content from day one. They land in SharePoint Embedded with labels honoured, which means a mislabelled reference file inside a skill is a data-classification problem, not a build problem. Get the compliance owner to look at the package contents before anyone uploads a real one.

---

Preview feature — worth revisiting once cross-agent reuse and the skills-plus-files restriction are resolved.