Use Agent Skills in VS Code

Agent Skills are folders of instructions, scripts, and resources that AI agents 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, the GitHub Copilot app, and the experimental OpenAI Codex integration.

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 across skills-compatible agents, but supported locations and optional features vary by agent. Unless otherwise noted, the configuration options and controls on this page apply to Copilot.

For how skills compare with the other customization options, see Customization concepts.

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:

For example, you can share a repository's .github/copilot-instructions.md between VS Code and GitHub Copilot CLI. Check the supported file locations and activation rules for each experience.

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

Use an existing skill

Start with an existing skill when it provides the workflow you need. You can install a skill from a supported marketplace source, use one bundled in an agent plugin, or copy and adapt one for your project. Check harness compatibility before choosing a source and location.

A skill includes its full directory, not only the SKILL.md file: scripts, templates, examples, and other resources can be part of the workflow.

Install a skill from the Customization Marketplace (Preview)

Use the Customization Marketplace to find and install skills from configured sources. Marketplace discovery is enabled by default. GitHub Feed requires a harness that provides marketplace search; Local sessions don't provide this source, and organization policy can restrict access.

1. Open the Agent Customizations editor and select Browse.
2. From the source menu, select GitHub Feed, and then search for a skill by name or add @type:skill to your search.
3. Select a skill and review its publisher, source, and included files.
4. Select Install, and choose a supported user or workspace destination when prompted.
5. Verify the installed skill in a session with the intended harness.

VS Code doesn't overwrite an existing skill at the selected destination. If another supported location contains a skill with the same name, both skills appear on the Skills page. The source or publisher image identifies the Marketplace installation, and Copy Relative Path shows its exact location.

VS Code tracks the directory of each skill installed from the Marketplace. Deleting that skill from the Skills page doesn't remove a local skill with the same name in another location.

If files from a Marketplace-installed skill are missing, Browse shows Missing files. Select Repair to restore only the missing packaged files. Files that you changed or added remain unchanged.

For more information about browsing sources and installation states, see Discover marketplace customizations.

Copy and adapt an existing skill

1. Review the skill's instructions, scripts, and other resources before adding it to your workspace.
2. Copy the entire skill directory to a supported project or personal location for your harness.
3. Adapt the SKILL.md file to your needs. Check commands, file paths, dependencies, and assumptions about the project.
4. Update any supporting scripts, templates, or examples that the adapted instructions use.
5. Verify the adapted skill before sharing it.

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. In the Chat view, select Open Customizations in the title bar to open the Agent Customizations editor, and then select Skills.

2. Select New Skill (plus icon) next to Workspace to store the skill in your project, or next to User to use it across your workspaces.

   

3. Choose a location if prompted, and enter a skill name, such as test-changes. The editor offers locations for the selected harness. See Skill locations for details.

4. In the generated SKILL.md file, describe what the skill does, when to use it, and the instructions to follow. For example:

   ---
   name: test-changes
   description: Run relevant project tests and report the results. Use when validating a code change.
   ---
   
   # Test changes
   
   1. Identify the tests that cover the changed code.
   1. Run them using the test commands documented in this repository.
   1. Report what passed, what failed, and any checks you couldn't run.
   

   Keep name consistent with the skill directory name. For additional fields, see the file format reference.

5. If the skill needs scripts, templates, or examples, add them to its directory and reference them from SKILL.md.

   Use Markdown links or #file: references with paths relative to SKILL.md, such as [test template](./test-template.js) or #file:./test-template.js.

6. Save the files and verify the skill.

Generate a skill with AI

Instead of writing the file yourself, ask the agent to create a skill in a chat with your intended harness. Describe the task, when the skill should apply, and where to store it. For example:

Create a project skill named test-changes in a location supported by this harness. It should identify and run the relevant tests for a code change using this repository's documented commands, then report what passed, failed, or wasn't run. Include a description of when to use the skill.

You can also ask the agent to turn a process from the current conversation into a skill, such as "create a skill from how we just debugged that." Review the generated instructions, file locations, and supporting resources, then verify the skill.

Local harness shortcuts

With Local selected in the Chat view, you can also:

• Enter /skills to open the Configure Skills menu.
• Enter /create-skill followed by a description to generate a skill.
• Select Generate with AI in the Skills section of the Agent Customizations editor.

For other harnesses, use Open Customizations or describe the skill directly in chat.

Verify a skill

Use these checks after installing, copying, creating, or editing a skill.

Start a fresh chat with the intended harness and workspace. If the skill appears in the / menu, run the skill yourself and give it a small task you expect it to handle. Review the tool activity and result to confirm that it uses the expected instructions and resources.

If you want the agent to select the skill automatically, test that separately with a request that matches its description. Discovery and installation make a skill available; they don't guarantee that the agent selects it for every relevant request.

Skill locations

Store project skills in the repository when you want to share them with contributors. Store personal skills in your home directory to use them across workspaces. Each skill has its own directory containing SKILL.md.

The following table gives a supported project and personal location for each harness, not every directory it recognizes. The Agent Customizations editor offers creation locations for the selected harness.

Codex

To reuse repository skills with OpenAI Codex, configure the experimental Codex integration. In addition to native .agents/skills/ discovery, this integration discovers workspace skills in .github/skills/ before your first prompt, without additional skill-location configuration.

If skills in .github/skills/ have duplicate names across workspace roots, the primary root takes precedence.

The Codex harness is disabled when Copilot enterprise-managed settings apply. Contact the IT team that deployed the settings to discuss access.

Local

Local sessions also read project skills from .claude/skills/ and .agents/skills/, and personal skills from ~/.claude/skills/ and ~/.agents/skills/.

The chat.agentSkillsLocations Open in VS Code Open in VS Code Insiders setting adds other skill locations for Local sessions. This setting is deprecated and isn't read by Copilot harness sessions. To reuse those skills with the Copilot harness, move them to supported locations.

Monorepos

If you open a subfolder of a monorepo, check the parent repository discovery requirements before storing skills above the open workspace folder.

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 by using Markdown links or the #file: syntax. For files within the skill directory, use paths relative to the SKILL.md file, such as [test script](./test-template.js). To reference your environment user home folder, use ~, or start a path with ~/, such as #file:~/skill-resources/test-template.js. Use Unix-style / path separators to keep skills portable across operating systems.

Run a skill in a forked context

By default, when VS Code loads a skill, the skill's instructions are added to the parent agent's context window. For large skills, or skills whose intermediate reasoning isn't relevant to the rest of your conversation, you can instead run the skill in a forked context. In a forked context, the skill executes in a dedicated subagent and only its final result is returned to the parent agent. This keeps your main conversation's context clean.

To run a skill in a forked context, set the context field in the SKILL.md frontmatter to fork:

---
name: review-pr
description: Review a pull request for code quality, style, and correctness. Use when asked to review a PR.
context: fork
---

# PR review

Follow these steps to review the pull request...

Use context: fork for skills that:

• Read many files or run lengthy investigations whose details don't need to stay in the main conversation
• Produce a focused result (such as a summary, a report, or a small set of edits) that the parent agent can act on directly
• Should not influence the parent agent's behavior beyond their final output

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-invocable and disable-model-invocation frontmatter properties to control how each skill is accessed:

How Copilot uses skills

Skills load content progressively to keep your context efficient. Here is an example of how Copilot uses the webapp-testing skill:

1. Discovery: Copilot reads the skill's name and description from the YAML frontmatter. When you ask "help me test the login page", Copilot matches this to the webapp-testing skill based on its description.

2. Instructions loading: Copilot loads the SKILL.md body into its context, giving it access to the detailed testing procedures and guidelines. You can also trigger this step directly by typing /webapp-testing in chat.

3. Resource access: As Copilot works through the instructions, it accesses additional files in the skill directory, such as test-template.js or example scenarios, only when it references them. If a file isn't referenced in the instructions, it won't be loaded.

This three-level loading system means you can install many skills without consuming context. Copilot loads only what is relevant for each task.

Skills that opt in to a forked context follow the same discovery step, but their instructions and any files they read are loaded into a separate subagent. Only the skill's final result is returned to the parent agent.

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 the corresponding SKILL.md file:

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

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 app: Available in the dedicated desktop experience.
• OpenAI Codex integration (Experimental): Discovers workspace skills in .github/skills/ after you set up the integration.

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
• Discover and manage agent plugins