Status: Preview labels removed from the core skills articles on 26 October 2026 (GA update); some related tooling, such as Work IQ Dev Tools, is still preview.
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
.zipup 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.mdinstructions 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_SKILLSenvironment variable. - The 26 October 2026 update drops the Frontier Program wording from the Agent Builder articles; the route still needs a qualifying Copilot licence (or PAYG), so confirm the licence position rather than assuming.
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
- Information Barriers tenants: admins can deploy declarative agents with skills, but end users can't add skills to agents they create.
- ISVs can't ship skills yet. Publishing a declarative agent with skills through Partner Center isn't available, and Microsoft says don't submit packages that include them.
- The older note that skills and embedded files can't be combined no longer appears in the current restrictions. Test that combination rather than trusting either version.
- 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
.zipin Agent Builder — a bareSKILL.mdis 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.
- Frontier enrolment used to kill more pilots than the technical limits did. The current docs no longer lead with it, but check what the tenant can actually see before it goes into a statement of work.
- Packaging for a marketplace is the new trap: ISV-style delivery through Partner Center isn't supported with skills, so a product-style agent has to be deployed per tenant for now.
- 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.
Newly out of preview — worth revisiting once cross-agent reuse and Partner Center publishing arrive.