Mastering Agent Skills in Copilot Studio and VS Code

AI agents rarely fail because they lack general knowledge. They fail because they do not know your procedure: which template to use, which checks to run, which tools are permitted, and what a valid result looks like.

Putting every procedure into one enormous system prompt is the obvious fix, but it is a poor architecture. The prompt becomes difficult to maintain, irrelevant instructions compete for attention, and every request carries context that most tasks do not need.

Agent Skills offer a more modular model. A skill packages task-specific instructions and, when supported by the host, related scripts, references, and assets. The agent sees a short description first and loads the detailed procedure only when the task calls for it.

This article explains that model, the SKILL.md format, progressive disclosure, and the practical differences between using skills in Microsoft Copilot Studio and GitHub Copilot in Visual Studio Code.

What an Agent Skill is

Think of an agent as a capable new colleague and a skill as a focused operating manual for one job.

The colleague already knows how to reason and communicate. The operating manual supplies the local method:

• the conditions under which the procedure applies;
• the steps to follow;
• the expected input and output;
• the tools or resources to use;
• the exceptions to handle; and
• the checks that define completion.

Under the open Agent Skills specification, a skill is a directory containing at least a SKILL.md file. It may also contain scripts, reference material, templates, examples, or other supporting files.

invoice-review/
├── SKILL.md
├── scripts/
│   └── validate_totals.py
├── references/
│   └── expense-policy.md
└── assets/
    └── review-template.md

This structure separates three kinds of knowledge that are often mixed together in a large prompt:

1. Routing metadata tells the host when the skill is relevant.
2. Procedural instructions tell the agent how to perform the task.
3. Supporting resources are loaded or used only when the procedure requires them.

That separation is the real value. A skill is not simply a longer prompt saved in a file. It is a reusable capability boundary.

Skills, instructions, knowledge, and tools are not the same thing

Agent platforms now expose several customization mechanisms. They overlap, but they solve different problems.

A useful rule is:

A skill can coordinate the other layers. For example, a release skill might tell the agent to consult a release policy, invoke a test tool, update a changelog, and stop if a required check fails. The skill describes the procedure; it does not magically create the tool or permission needed to execute it.

This distinction corrects a common misconception: including a Python file in a skill does not guarantee that every compatible agent can run Python. Execution depends on the host’s available tools, security model, approvals, and runtime. The open specification defines a package format, not a universal execution environment.

Why progressive disclosure matters

Agent Skills use progressive disclosure. Instead of loading every instruction and resource at once, the host reveals information in stages.

1. Discovery

The host advertises compact metadata, principally the skill’s name and description. This gives the agent enough information to judge relevance without loading the full procedure.

2. Activation

When a request matches the skill’s purpose, the host loads the SKILL.md instructions into the active context.

3. Resource loading and execution

The agent follows the procedure and accesses referenced files or invokes available tools as needed. A large policy document, template, or script does not need to occupy the context before it becomes relevant.

The mental model is a library index. The agent first sees the catalog card, then opens the right book, then reads the appendix only if the chapter directs it there.

This reduces unnecessary context use, but it should not be sold as a guaranteed token-saving figure. Actual savings depend on the host implementation, the number and size of skills, the task, and which resources are loaded. The defensible claim is that on-demand loading can reduce irrelevant context compared with injecting every procedure into every conversation.

Anatomy of SKILL.md

A valid SKILL.md contains YAML frontmatter followed by Markdown instructions.

---
name: invoice-review
description: Reviews invoice files, checks required fields and totals, and produces a structured exception report. Use when a user asks to validate or review an invoice.
license: Proprietary
compatibility: Requires access to the invoice files and a Python runtime for optional validation.
metadata:
  owner: finance-automation
  version: "1.0"
---

# Invoice review procedure

1. Confirm that the invoice file is available.
2. Extract the supplier, invoice number, date, currency, line items, tax, and total.
3. Run `scripts/validate_totals.py` if the host provides an approved Python execution tool.
4. Compare any exceptions with `references/expense-policy.md`.
5. Return the result using `assets/review-template.md`.
6. If a required field is missing, report it rather than inventing a value.

Required frontmatter

The open specification requires two fields:

• name: 1 to 64 characters, using lowercase letters, numbers, and hyphens. It must not begin or end with a hyphen, contain consecutive hyphens, and should match the parent directory name.
• description: 1 to 1,024 characters describing both what the skill does and when it should be used.

The specification also defines optional fields including license, compatibility, metadata, and allowed-tools. However, allowed-tools is experimental and support can vary by implementation. Treat optional metadata as portable only after testing it in each target host.

The description is a routing contract

The description is not marketing copy. It is part of the activation mechanism.

A weak description says:

description: Helps with invoices.

A stronger description says:

description: Reviews invoice files, validates required fields and totals, and produces an exception report. Use when a user asks to inspect, check, reconcile, or validate an invoice.

The stronger version identifies the task, expected behavior, and likely user language. That makes correct activation more likely and accidental activation less likely.

The instruction body is an operating procedure

Good skill instructions specify:

• prerequisites and required inputs;
• ordered steps;
• tool and resource usage;
• expected output format;
• validation criteria;
• failure and escalation behavior; and
• explicit prohibitions, such as not inventing missing values.

Avoid vague commands such as “review carefully” or “use best practices.” If consistency matters, define what the review checks and what the result must contain.

Designing a skill package

The specification allows flexible supporting content, but a simple convention works well:

my-skill/
├── SKILL.md          # Routing metadata and core procedure
├── scripts/          # Deterministic processing or validation
├── references/       # Material the agent may need to read
└── assets/           # Templates and static files used in outputs

Keep SKILL.md focused on orchestration. Microsoft Agent Framework guidance recommends keeping it below 500 lines and moving detailed material into supporting files. This is a practical guideline rather than a universal runtime limit.

Use relative file references and state exactly when a resource should be opened. “Read every file in references/” defeats progressive disclosure. “Read references/tax-rules.md only when the invoice contains tax” is much sharper.

Building skills in Microsoft Copilot Studio

Copilot Studio’s new agent experience supports reusable Markdown-based skills. Microsoft documents two primary authoring paths: create a skill from blank or upload an existing skill file or package.

Option 1: Create a skill from blank

Use this path when the capability is mostly instructional and does not require bundled files.

1. Open an agent created in the new Copilot Studio experience.
2. Go to Build.
3. In the components panel, select Skills.
4. Select Add skill, then Create from blank.
5. Enter a lowercase, hyphenated name.
6. Write a description that explains what the skill does and when it should activate.
7. Add Markdown instructions, including steps, output constraints, edge cases, and relevant tool references.
8. Create the skill and test representative prompts in the Preview experience.

The original demonstration uses a deliberately simple hello-art skill. Its description is intended to match a request for an artistic greeting, while its instructions require the words “Hello Girish” as large ASCII-style text, request a red presentation, and prohibit extra response text. After saving the agent, the presenter opens a new preview chat, enters a matching request, and observes that Copilot Studio loads the skill and applies its output constraints.

That example is useful because it makes activation visible, but it also exposes an important design limit: a text-only response channel might not reliably honor a color request. For a production skill, define constraints that the target channel can actually represent. A standardized incident summary is a more operational example: require impact, affected systems, timeline, mitigation, owner, and next update, then return those fields in a fixed Markdown structure.

Option 2: Upload a Markdown skill

Use a single Markdown file when the procedure is self-contained.

1. In Build > Skills, select Add skill.
2. Select Upload a skill.
3. Upload the Markdown file containing YAML frontmatter and instructions.
4. Let Copilot Studio validate and add it.
5. Test activation, non-activation, output quality, and failure behavior.

If you change an uploaded skill externally, replace the existing version with the updated file. Microsoft distinguishes this from a skill created from blank, whose fields can be edited within the skill configuration panel.

The source demonstration uses a single-file generate-pdf skill to illustrate this path. The skill contains YAML frontmatter, instructions, and an embedded example that collects a title and body before producing a PDF. In Preview, a request such as “generate PDF” activates the skill, which then asks for missing content before continuing. The educational point is not that every uploaded Markdown file gains a universal PDF runtime. It is that the skill can define both a multi-turn input-gathering procedure and the implementation steps to use when the host provides the required execution capability.

Option 3: Upload a ZIP package

Use a ZIP package when the skill depends on scripts, templates, or reference documents.

The archive must include SKILL.md and may include supporting files. Before uploading, inspect the archive structure and ensure SKILL.md is where Copilot Studio expects it, rather than accidentally burying it inside an extra wrapper directory.

incident-summary.zip
├── SKILL.md
├── references/
│   └── severity-model.md
└── assets/
    └── incident-summary-template.md

Package files should still be treated as instructions and resources, not as automatically trusted executables. The agent can only use a script if the target environment exposes an appropriate execution mechanism and permits the action.

The source demonstrates this package model with a run-python-math skill and a separate hello.py file. The instructions tell the agent to run the script and return its output directly. The script prints a short message and adds 100 + 22, producing 122. After upload, Copilot Studio displays both files; a matching Preview request activates the skill and, in the demonstrated environment, executes the script. That observed result is worth preserving, but it should be described as host behavior shown in the preview, not as a guarantee of the open specification.

Packaging detail that matters

The source demonstration packages SKILL.md and hello.py at the top level of the ZIP rather than zipping an extra parent folder around them:

run-python-math.zip
├── SKILL.md
└── hello.py

This is a safe packaging pattern because the required file is immediately visible when the archive is opened. Microsoft states that a ZIP skill package must include SKILL.md; it does not document every archive-layout edge case, so validate the exact package in Copilot Studio rather than relying on the ZIP filename or folder structure alone. The ZIP itself can have a descriptive filename, but the required manifest inside the package is SKILL.md.

Editing and downloading packaged skills

The source demonstration shows a useful lifecycle difference: a skill created from blank can be edited in Copilot Studio, while the files displayed inside an uploaded package are treated as package content. For packaged skills, keep the source in your repository, make changes in VS Code or another editor, rebuild the ZIP, and replace the uploaded version. The demonstration also shows an option to download the package. Because these interface details can change during preview, verify them in the current tenant experience before documenting them as a permanent administrative contract.

Do not confuse this with legacy Bot Framework skills

Copilot Studio documentation also uses the term skill for integrations built with the Microsoft 365 Agents SDK or the legacy Bot Framework SDK. Those are hosted conversational components registered with an agent and involve app registration, authentication, and deployment.

The Markdown-based Agent Skills discussed in this article are a different model: portable task instructions and supporting files in the new agent experience. When searching documentation, confirm which meaning of “skill” the page describes.

Using Agent Skills with GitHub Copilot in VS Code

GitHub Copilot in Visual Studio Code supports project and personal skills. Each skill gets its own directory containing SKILL.md.

Project skills

Store repository-specific skills under one of the supported project locations:

.github/skills/
.claude/skills/
.agents/skills/

For example:

.github/skills/release-check/
├── SKILL.md
├── scripts/
│   └── verify-release.sh
└── references/
    └── release-policy.md

Project skills can be committed to source control, reviewed with the codebase, and shared with the team. A repository can contain multiple skill directories, each organized around a distinct use case. This is the practical meaning of a skill hierarchy: the parent skills directory is a catalog, and each child directory is an independently discoverable capability.

Personal skills

VS Code documentation lists these personal locations:

~/.copilot/skills/
~/.claude/skills/
~/.agents/skills/

GitHub’s cross-product documentation lists ~/.copilot/skills/ and ~/.agents/skills/. Because supported locations can differ by client and version, follow the documentation for the exact host you use.

Creating and managing skills

In current VS Code documentation, you can open the Agent Customizations editor from Copilot Chat or run Chat: Open Customizations from the Command Palette. The Skills view lets you create workspace or user skills. Typing /skills in chat also opens the skill configuration menu.

You can configure additional project locations with chat.agentSkillsLocations. This is helpful in monorepos or repositories with an established customization structure.

The original article referred broadly to “Visual Studio.” The currently verified documentation used for this guide applies to Visual Studio Code. Do not assume identical discovery paths or management interfaces in the full Visual Studio IDE without checking that product’s current documentation.

A practical design workflow

The cleanest way to build a reliable skill is to start with behavior, not folders.

Step 1: Define one narrow job

Bad scope: “Handle software delivery.”

Better scope: “Diagnose failed GitHub Actions jobs and produce a proposed fix with validation steps.”

A skill should be narrow enough that its activation criteria and completion criteria are obvious.

Step 2: Write the activation description

Include:

• the artifact or domain;
• the action the skill performs;
• the situations that should trigger it; and
• important exclusions if confusion with another skill is likely.

Step 3: Write the procedure

Describe the sequence the agent should follow. Identify decisions, stopping conditions, and what to do when required information is absent.

Step 4: Separate deterministic work

Use scripts for calculations, parsing, validation, or transformations that should not depend on model judgment. Keep interpretation, coordination, and explanation in the instructions.

Step 5: Move bulky material out of the core file

Place long policies, examples, schemas, and templates in supporting files. Tell the agent when each one is relevant.

Step 6: Test activation and resistance

Test at least four classes of prompts:

1. Direct match: The skill should activate.
2. Paraphrased match: Different wording should still activate it.
3. Near miss: A related but out-of-scope request should not activate it.
4. Adversarial or incomplete input: The skill should fail safely and request or report missing information.

Then inspect not only the final answer but also whether the agent selected the right resources and respected the defined constraints.

Common mistakes

Treating every instruction as a skill

A universal rule such as “use PascalCase for C# types” belongs in repository instructions. A skill is appropriate when there is a distinct task with a procedure and completion condition.

Writing a vague description

If two skills both say they “help with documents,” the orchestrator has little basis for choosing. Descriptions should create clear semantic boundaries.

Assuming portability means identical behavior

The file format can be portable while runtime behavior is not. Different hosts may expose different tools, resource-loading behavior, approvals, limits, and optional-field support.

Assuming bundled code will run automatically

A script is a resource until the host provides an execution tool and permission to invoke it. Describe runtime requirements in compatibility, document expected inputs and outputs, and test in every target environment.

Loading all references up front

This recreates the large-prompt problem inside the skill. Keep the core procedure concise and load supporting material conditionally.

Trusting community skills without review

A community skill can contain instructions, scripts, and references that influence agent behavior or request local actions. Review the full package, its license, dependencies, network requirements, and scripts before installation. Pin or version the copy you approve, and test it in a constrained environment.

Where to find the specification and examples

Start with authoritative sources:

• Agent Skills specification for the portable file format and field constraints.
• Copilot Studio skills overview for the new Copilot Studio experience and its preview status.
• Create a skill in Copilot Studio and upload an existing skill for current authoring steps.
• Agent Skills in VS Code for discovery locations and the customization interface.
• GitHub Copilot Agent Skills for cross-product GitHub Copilot guidance.
• Agent Skills in Microsoft Agent Framework for a code-first implementation model and detailed progressive-disclosure guidance.

Community collections can accelerate discovery, but they are not substitutes for review. The source specifically points to skills.sh as a place to search for reusable skills covering technologies such as Copilot and Azure. The GitHub awesome-copilot repository is another catalog of community customizations. These are discovery channels, not authoritative compatibility guarantees. Verify the publisher, license, files, scripts, dependencies, and target-host behavior before adopting any community package.

The bigger architectural lesson

Agent Skills are useful because they turn agent behavior into modular, inspectable artifacts.

Instead of one overloaded prompt, you get a set of focused procedures. Instead of repeatedly explaining a workflow, you version it. Instead of filling the context with every policy and template, you load material when the task needs it.

The most productive mental model is not “install a superpower.” It is publish an operating procedure that an agent can discover and follow.

That framing keeps expectations realistic. Skills can improve reuse, consistency, and context efficiency, but they do not replace tools, permissions, testing, or sound procedure design. A well-written SKILL.md tells the agent what good work looks like. The host environment still determines what the agent can actually do.