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 two types of skills:

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
```

To debug tests:
```bash
npx playwright test --debug
```

## Best practices

- Use data-testid attributes for dynamic content
- Keep tests independent and atomic
- Use Page Object Model for complex pages
- Take screenshots on failure

---
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

Use skills as slash commands

Skills are available as slash commands in chat, alongside prompt files. Type / in the chat input field to see a list of available skills and prompts, and select a skill to invoke it.

You can add extra context after the slash command. For example, /webapp-testing for the login page or /github-actions-debugging PR #42.

By default, all skills appear in the / menu. Use the user-invokable and disable-model-invocation frontmatter properties to control how each skill is accessed:

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. You can also directly invoke a skill by using the / slash command in chat.

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 both automatically activated based on your prompt and manually invocable through slash commands. You can install many skills, and Copilot loads 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

Contribute skills from extensions

Extensions can contribute skills using the chatSkills contribution point in their package.json. The path must point to a directory that contains a SKILL.md file, following the Agent Skills specification.

Required folder structure

The skill directory must follow this structure:

extension-root/
└── skills/
    └── my-skill/           # Directory name must match the `name` field in SKILL.md
        └── SKILL.md         # Required

Register the skill in package.json

Add the chatSkills contribution point in your extension's package.json. The path property must point to a directory that contains a SKILL.md file:

{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill"
      }
    ]
  }
}

The SKILL.md file follows the same format as project and personal skills. For example:

---
name: my-skill
description: Description of what the skill does and when to use it.
---

# My Skill

Detailed instructions for the skill...

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