Compose and package a skill for reuse
Once a skill's instructions describe a task correctly, two composition questions decide whether other agents and other teams can use it. Does the skill direct the agent to specific components, such as tools, that other agents might not have configured? And how do you package the skill so it travels as a single artifact?
Direct a skill to specific tools
A skill's instructions can call out specific tools the agent should use while the skill is active. A tool reference inside a skill's instructions reads as a plain-language directive:
## Steps
1. Collect the customer's account number and the date range of the issue.
2. Use the **Ticket lookup** tool to retrieve the matching support tickets.
3. Summarize the tickets in a bullet list, most recent first.
The value of naming a tool inside a skill is that the skill's behavior stays consistent regardless of what else the agent's identity or default guidance suggests. When the skill is active, the agent knows exactly which tool to use for the operation the skill needs. Without the reference, the orchestrator picks a tool based on the request and the tool descriptions available, which is fine for open-ended requests but can be unpredictable for a skill that depends on a specific data source.
Design cost of coupling a skill to a tool
The design cost is that a tool reference couples the skill to that tool. If you upload the same skill into an agent that doesn't have the referenced tool configured, the skill either fails on the step that names the tool or falls back to whatever behavior the agent's default instructions allow. Two portability disciplines keep the coupling manageable:
- Reference tools by role, not by internal name, wherever possible. A skill that says "use the tool that retrieves support tickets" reads as a requirement other agents can satisfy with equivalent tools. A skill that hard-codes an internal tool name is only reusable in agents that expose an identically named tool.
- State tool dependencies in the skill's description or opening instructions. Makers adopting the skill can see what the skill depends on before they upload it, and can decide whether to configure the equivalent tools first or adapt the skill's instructions.
Cost implications of tool references
Skills that reference tools also carry cost implications. When the skill is active, each tool invocation the instructions direct is an additional operation the agent performs, and the more tools a skill fans out to, the more work each activation drives. Design a skill's tool references to what the task requires, not to what a broader pattern could touch.
Choose between SKILL.md and a ZIP package
Copilot Studio accepts two skill artifact formats. Choose between them based on what the skill needs to ship.
Ship a single SKILL.md file
Use a single Markdown file (typically named SKILL.md) when the skill's behavior lives entirely in the instructions. The file contains YAML front matter with the skill's name and description, then the Markdown instructions:
---
name: monthly-report-generator
description: Handles monthly reporting requests, including generating summary tables and formatting them for stakeholder review.
---
## Task
Generate a monthly summary report from the data the user provides…
## Steps
1. Confirm the reporting period with the user.
2. Ask which stakeholder audience the report is for.
3. Generate the summary table in the format requested.
## Edge cases
If the user hasn't provided the underlying data, request it before continuing.
A single Markdown file is the right choice for pure-instruction skills: behaviors an agent can execute using only the guidance in the instructions plus components the host agent already has configured.
Ship a ZIP package
Use a ZIP package when the skill ships supporting files the instructions reference. The ZIP must contain a SKILL.md file at its root; alongside it, you can include scripts, templates, or reference documents the skill's instructions call out. A ZIP is the right choice when:
- The instructions reference a specific report template, prompt template, or checklist the agent needs to load or return verbatim.
- The skill includes a script the agent runs to complete the task.
- The skill ships reference material, such as policy excerpts, that the instructions direct the agent to consult.
Required YAML front matter
Whichever format you choose, the YAML front matter of the SKILL.md file follows the same shape. The documented required fields are:
name: The skill's identifier, following the naming rules (lowercase, numbers, hyphens; no leading or trailing hyphen; unique in the target agent).description: A single-line summary the orchestrator uses to match user requests to the skill.
The Markdown body below the front matter carries the instructions. Common structural conventions in that body, including task description, steps, edge cases, and any tool references, are recommended patterns for effective skill instructions, not additional required schema fields.
Note
If a pre-built skill fails to load after upload, the most common causes are invalid YAML front matter or a missing name or description value.
Package for the reuse target
Package format influences how portable a skill is. A single Markdown file is easy to review in a text editor, easy to hand off in a chat message or a documentation repository, and easy to update by editing one file and replacing it in each agent that uses it. A ZIP is a larger unit of work: any agent that adopts it needs the same set of supporting files present, and updating the skill means re-exporting the ZIP and replacing it everywhere.
A useful heuristic: if the skill's behavior can be captured cleanly in instructions alone, ship it as a Markdown file. Move to a ZIP only when the skill depends on supporting files, and account for the maintenance cost of keeping those files in sync as the skill evolves.