Use Agent Skills in VS Code

Agent Skills are folders of instructions, scripts, and resources that GitHub Copilot can load when relevant to perform specialized tasks. Agent Skills is an open standard that works across multiple AI agents, including GitHub Copilot in VS Code, GitHub Copilot CLI, and GitHub Copilot coding agent.

Unlike custom instructions that primarily define coding guidelines, skills enable specialized capabilities and workflows that can include scripts, examples, and other resources. Skills you create are portable and work across any skills-compatible agent.

Key benefits of Agent Skills:

• Specialize Copilot: Tailor capabilities for domain-specific tasks without repeating context
• Reduce repetition: Create once, use automatically across all conversations
• Compose capabilities: Combine multiple skills to build complex workflows
• Efficient loading: Only relevant content loads into context when needed

Agent Skills vs custom instructions

While both Agent Skills and custom instructions help customize Copilot's behavior, they serve different purposes:

Use Agent Skills when you want to:

• Create reusable capabilities that work across different AI tools
• Include scripts, examples, or other resources alongside instructions
• Share capabilities with the wider AI community
• Define specialized workflows like testing, debugging, or deployment processes

Use custom instructions when you want to:

• Define project-specific coding standards
• Set language or framework conventions
• Specify code review or commit message guidelines
• Apply rules based on file types using glob patterns

Create a skill

Skills are stored in directories with a SKILL.md file that defines the skill's behavior. VS Code supports skills in two locations:

• .github/skills/ - The shared location recommended for all new skills used by Copilot
• .claude/skills/ - Legacy location, also supported for backward compatibility

To create a skill:

1. Create a .github/skills directory in your workspace.

2. Create a subdirectory for your skill. Each skill should have its own directory (for example, .github/skills/webapp-testing).

3. Create a SKILL.md file in the skill directory with the following structure:

   ---
   name: skill-name
   description: Description of what the skill does and when to use it
   ---
   
   # Skill Instructions
   
   Your detailed instructions, guidelines, and examples go here...
   

4. Optionally, add scripts, examples, or other resources to your skill's directory.

   For example, a skill for testing web applications might include:

   • SKILL.md - Instructions for running tests
   • test-template.js - A template test file
   • examples/ - Example test scenarios

SKILL.md file format

The SKILL.md file is a Markdown file with YAML frontmatter that defines the skill's metadata and behavior.

Header (required)

The header is formatted as YAML frontmatter with the following fields:

Body

The skill body contains the instructions, guidelines, and examples that Copilot should follow when using this skill. Write clear, specific instructions that describe:

• What the skill helps accomplish
• When to use the skill
• Step-by-step procedures to follow
• Examples of the expected input and output
• References to any included scripts or resources

You can reference files within the skill directory using relative paths. For example, to reference a script in your skill directory, use [test script](./test-template.js).

Example skills

The following examples demonstrate different types of skills you can create.

---
name: webapp-testing
description: Guide for testing web applications using Playwright. Use this when asked to create or run browser-based tests.
---

# Web Application Testing with Playwright

This skill helps you create and run browser-based tests for web applications using Playwright.

## When to use this skill

Use this skill when you need to:
- Create new Playwright tests for web applications
- Debug failing browser tests
- Set up test infrastructure for a new project

## Creating tests

1. Review the [test template](./test-template.js) for the standard test structure
2. Identify the user flow to test
3. Create a new test file in the `tests/` directory
4. Use Playwright's locators to find elements (prefer role-based selectors)
5. Add assertions to verify expected behavior

## Running tests

To run tests locally:
```bash
npx playwright test

npx playwright test --debug

</details>

<details>
<summary>Example: GitHub Actions debugging skill</summary>

```markdown
---
name: github-actions-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---

# GitHub Actions Debugging

This skill helps you debug failing GitHub Actions workflows in pull requests.

## Process

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs
3. If you need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full failure logs
4. Try to reproduce the failure locally in your environment
5. Fix the failing build and verify the fix before committing changes

## Common issues

- **Missing environment variables**: Check that all required secrets are configured
- **Version mismatches**: Verify action versions and dependencies are compatible
- **Permission issues**: Ensure the workflow has the necessary permissions
- **Timeout issues**: Consider splitting long-running jobs or increasing timeout values

How Copilot uses skills

Skills use progressive disclosure to efficiently load content only when needed. This three-level loading system ensures you can install many skills without consuming context:

Level 1: Skill discovery

Copilot always knows which skills are available by reading their name and description from the YAML frontmatter. This metadata is lightweight and helps Copilot decide which skills are relevant to your request.

Level 2: Instructions loading

When your request matches a skill's description, Copilot loads the SKILL.md file body into its context. Only then do the detailed instructions become available.

Level 3: Resource access

Copilot can access additional files in the skill directory (scripts, examples, documentation) only as needed. These resources don't load until Copilot references them, keeping your context efficient.

This architecture means skills are automatically activated based on your prompt—you don't need to manually select them. You can install many skills, and Copilot will load only what's relevant for each task.

Use shared skills

You can use skills created by others to enhance Copilot's capabilities. The github/awesome-copilot repository contains a growing community collection of skills, custom agents, instructions, and prompts. The anthropics/skills repository contains additional reference skills.

To use a shared skill:

1. Browse the available skills in the repository
2. Copy the skill directory to your .github/skills/ folder
3. Review and customize the SKILL.md file for your needs
4. Optionally, modify or add resources as needed

Agent Skills standard

Agent Skills is an open standard that enables portability across different AI agents. Skills you create in VS Code work with multiple agents, including:

• GitHub Copilot in VS Code: Available in chat and agent mode
• GitHub Copilot CLI: Accessible when working in the terminal
• GitHub Copilot coding agent: Used during automated coding tasks

Learn more about the Agent Skills standard at agentskills.io.

Related resources

• Customize AI responses overview
• Create custom instructions
• Create reusable prompt files
• Create custom agents
• Agent Skills specification
• Reference skills repository