Build Your First Agent Skill: A Quickstart Guide for VS Code and GitHub Copilot

This guide walks you through creating a portable Agent Skill that gives an AI assistant the ability to roll dice using a random number generator. You will write a single SKILL.md file, place it in the right folder, and test it in VS Code with GitHub Copilot. The same skill works in any compatible agent, including Claude Code and OpenAI Codex.

What it does

An Agent Skill is a lightweight, open-format instruction file that teaches an AI agent a new capability. When you ask the agent to perform a task that matches the skill's description, the agent loads the skill's instructions and executes them. In this tutorial, you create a skill that lets the agent roll a die (d6, d20, etc.) by running a terminal command. The agent discovers the skill automatically, activates it when relevant, and follows the steps you provide.

Before you start

You need:

• VS Code with the GitHub Copilot extension installed.

  This tutorial uses VS Code, but the skill format is open. The same SKILL.md file works in any agent that supports the Agent Skills specification, such as Claude Code or OpenAI Codex.

No other dependencies, accounts, or permissions are required beyond a working VS Code installation with Copilot enabled.

Create the skill

A skill is a folder containing a SKILL.md file. VS Code looks for skills in .agents/skills/ by default. Create the folder and file at .agents/skills/roll-dice/SKILL.md in your project:

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

That is the entire skill: one file, under 20 lines. Here is what each part does:

• name, A short identifier for the skill. It must match the folder name (roll-dice).
• description, Tells the agent when to use this skill. The agent matches your question against this description to decide whether to activate the skill.
• The body, Instructions the agent follows when the skill activates. Here, the agent is told to generate a random number using a terminal command, substituting the number of sides from the user's request. Both Bash and PowerShell versions are provided so the skill works on Linux, macOS, and Windows.