Mastering Agent Skills in Visual Studio Code: A Practical Guide

Agent skills have arrived for Visual Studio Code. If the thought of learning yet another new feature makes you weary, rest assured. Agent skills are surprisingly simple to grasp and remarkably powerful.

In this article, we’ll explore what they are and how they function. We will build one from scratch. Then, we’ll clarify the distinctions between skills, prompt files, instructions, and custom agents.

What Are Agent Skills?

At their core, skills are another method for providing instructions to an AI model. They possess distinct advantages over custom instructions, primarily their ability to bundle scripts, templates, and various files to define a complete capability. This might not seem clear at first. Seeing one in action or building one yourself is the best way to understand.

Let’s dive in and build one.

Setting Up Your Environment

We’re working within Visual Studio Code. It’s important to note that “skills” are a specification from Anthropic, meaning they are compatible with Claude Code and other platforms. However, our focus here is on Copilot.

At the time of this writing, skills are an experimental feature. To use them, you must enable them in your settings. If skills aren’t working for you, check to ensure this feature is toggled on.

Skills are essentially instruction files that must be placed in a specific directory. The agent looks for them in .github/skills, .copilot/skills, or .claude/skills at the root of your project.

Building Your First Skill: Hello World

Let’s start with an empty project and create our first skill.

1. Create a new folder at the root of your project named .github.
2. Inside .github, create a skills folder.
3. Inside skills, create a folder for our new skill, let’s call it hello-world.
4. Finally, inside the hello-world folder, create a new file named skill.md.

This skill.md file is the heart of our skill. It requires specific metadata at the top: a name and a description.

name: Hello World
description: A simple skill that responds when you enter the phrase "hello world".

Being as descriptive as possible with the name and description is crucial. The agent uses this information to automatically determine when to use a skill without you explicitly telling it to in the chat.

With the metadata in place, we can write the instructions for the model.

name: Hello World
description: A simple skill that responds when you enter the phrase "hello world".

This is the hello world skill. Use the hello world skill to respond to the user when they enter the phrase "hello world" in the chat.

When they do that, respond with "hello world" and ASCII art.

Our instructions are simple: when the user says “hello world,” respond with the same phrase and some fun ASCII art.

Now, how do we use this? Open the chat window and ask, “what skills do you have?” The model will examine the workspace and report back on the skills it has discovered.

It should respond with something like:

I have access to domain-specific skills. Hello world: A simple skill that responds when you enter the phrase “hello world”.

To trigger the skill, all we need to do is type “hello world” into the chat. The agent should recognize the trigger phrase, load the skill’s instructions, and respond appropriately.

 _    _      _ _                            _     _
| |  | |    | | |                          | |   | |
| |__| | ___| | | ___   __      _____  _ __| | __| |
|  __  |/ _ \ | |/ _ \  \ \ /\ / / _ \| '__| |/ _` |
| |  | |  __/ | | (_) |  \ V  V / (_) | |  | | (_| |
|_|  |_|\___|_|_|\___/    \_/\_/ \___/|_|  |_|\__,_|

Success! The agent followed our instructions perfectly. But you might be thinking, couldn’t we have done this with a simple instructions file or a prompt file? Yes. So, what makes skills special?

Modularizing Your Skill with Scripts and Templates

The true power of skills lies in their ability to bundle multiple files. Let’s make our skill more complex to demonstrate this.

We’ll modify the skill.md to include a script that gathers information about the user’s operating system.

name: Hello World
description: A simple skill that responds when you enter the phrase "hello world".

### Workflow
1. Run the following script to get system information.
   ```javascript
   const os = require('os');

   console.log(`Platform: ${os.platform()}`);
   console.log(`Type: ${os.type()}`);
   console.log(`Release: ${os.release()}`);
   console.log(`Architecture: ${os.arch()}`);

1. Respond with “hello world” and ASCII art.
2. Provide the system information obtained from the script. ```

Now, when we trigger the “hello world” prompt, the skill will execute a more complex workflow: run the script in the terminal, generate the ASCII art, and then return the system information as part of the response.

This works, but if the skill becomes very long—for instance, if we were teaching the AI how to write API endpoints for our company—this inline approach would become unwieldy. Skills allow you to modularize.

Let’s create a scripts folder inside our hello-world skill directory. Inside scripts, we’ll create a file named get-system-info.js and move our script there.

get-system-info.js:

const os = require('os');

console.log(`Platform: ${os.platform()}`);
console.log(`Type: ${os.type()}`);
console.log(`Release: ${os.release()}`);
console.log(`Architecture: ${os.arch()}`);

Now, we can reference this script in our skill.md using a relative path.

skill.md (updated):

name: Hello World
description: A simple skill that responds when you enter the phrase "hello world".

### Workflow
1. Run the script at `./scripts/get-system-info.js` to obtain system information.
2. Respond with "hello world" and ASCII art.
3. Provide the system information obtained from the script.

The result is the same, but our skill is now cleaner and more organized.

We can take this a step further with templates. Let’s create a new file in the hello-world directory called template.md. This file will define the exact format of the model’s response.

template.md:

Hello! You've triggered the "Hello World" skill.



Here is your system information:


Feel free to ask if you need any further assistance.

Now, we update our skill.md one last time to use this template.

skill.md (final):

name: Hello World
description: A simple skill that responds when you enter the phrase "hello world".

### Workflow
1. Run the script at `./scripts/get-system-info.js` to obtain system information.
2. Respond using the format defined in `./template.md`.

When we run it again, the output is perfectly formatted according to our template. The model is exceptionally good at following these structured instructions. This is the essence of what skills provide: a modular, powerful way to define complex agent behaviors. You could provide a database schema, multiple scripts, or detailed documentation—the possibilities are vast.

How Skills Work: Progressive Loading

One of the most interesting features of skills is that they are progressively loaded, which prevents them from consuming excessive space in the context window.

If we inspect the agent’s process using a debug view, we can see how this works:

1. Initial Pass: On the first request, the only information sent to the model is the skill’s name, description, and file path. The body of the skill and its associated files are not included.
2. Second Pass: The agent, seeing the user’s prompt, decides it needs to use the skill. It then makes a call to read the contents of the skill.md file.
3. Execution: Once it has the skill’s instructions, it sees that it needs to run a script. It executes the script and gets the terminal output.
4. Templating: Next, it reads the template.md file to understand how to structure the final response.
5. Final Response: Finally, it assembles all the gathered information into the final response for the user.

This progressive loading makes skills super efficient, as the agent only loads the information it needs, precisely when it needs it.

A More Complex Use Case: Reading PDFs

So, when should you use a skill? Technically, the agent can do almost anything since it can run any command in your terminal. However, there are many things it doesn’t know how to do.

For instance, if you ask the agent to read a PDF file, it will likely fail because it lacks built-in support for that file type. We can use a skill to teach it how.

Instead of building this from scratch, we can leverage existing skills from the community. The awesome-copilot and anthropic/skills repositories on GitHub are great resources. In the Anthropic repo, there is a pre-built pdf skill.

By cloning that repository and copying the pdf skill into our project’s .github/skills directory, we instantly teach our agent how to work with PDFs. The skill contains the necessary scripts and instructions to extract text from PDF files.

With the skill added, we can simply ask the agent to read a PDF, and it will use the scripts provided by the skill to extract the contents and answer our questions. We’ve taught the agent a new skill.

When to Use Skills vs. Other Instruction Methods

With agents being new, we’re still discovering the best practices for all the tools at our disposal. Here’s a general guideline for when to use each type of instruction method:

• Instructions File (.instructions): Use this for general information about the project that needs to be passed to the model with every single prompt.
• Prompt File (.prompt): Ideal for short, reusable prompts that you find yourself using frequently.
• Custom Agent: Use this when you want to define and enforce specific, repeatable workflows for the agent to follow every time.
• Skill: Everything else is likely a skill. If you need to bundle files, run scripts, use templates, or teach the agent a new, complex capability, a skill is the right tool for the job.

Ultimately, these are all building blocks. There isn’t a single right or wrong way to use them. They are different tools in your toolbox to help you and your team build the most effective and efficient workflow.

Agent skills support is available today in both VS Code Insiders and Stable. Just remember to enable the experimental setting, and you can start building right away.