How to add Agent Skills in VS Code

Agent Skills are folders of instructions, scripts, and resources that GitHub Copilot in VS Code can load when a task needs a specialized workflow. The format is an open standard, so a skill already written for another compatible agent can be discovered here if the folder matches a documented location. Custom instructions are a separate customization: they mainly define coding guidelines and stay applied, or apply by glob patterns. A skill is task-specific, loaded on demand, and can include scripts, examples, and other files beside the instructions.

Portability has a limit the docs state directly. 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 the Agent Skills page apply to Copilot.

Where project and personal skills are discovered

A skill is a directory that contains a SKILL.md file. VS Code discovers two kinds:

Project skills, stored in the repository: .github/skills/, .claude/skills/, and .agents/skills/
Personal skills, stored in your user profile: ~/.copilot/skills/, ~/.claude/skills/, and ~/.agents/skills/

Those paths are why a skill kept for another agent can show up in Copilot without a second format. If SKILL.md already lives under .claude/skills/ or .agents/skills/, that is a documented discovery location for both project and personal skills.

Discovery makes the skill available to the model. It does not guarantee that the model invokes the skill for every relevant prompt. If skills in .github/skills/ have duplicate names across workspace roots, the primary root takes precedence.

chat.agentSkillsLocations is deprecated and only used by the Local agent. If you configured other skill locations with that setting, migrate those skills to the supported locations above. In a monorepo, enable chat.useCustomizationsInParentRepositories to discover skills from the parent repository root.

To reuse repository skills with OpenAI Codex, set up Codex on Agent Host (Experimental). That integration discovers workspace skills in .github/skills/ before your first prompt, without additional skill-location configuration. Codex also discovers .agents/skills/ natively.

Open Configure Skills and create a skill

Type /skills in the chat input to open the Configure Skills menu. Skills from installed agent plugins appear there alongside skills you defined locally.

To create a skill from the editor:

In the Chat view, select Configure Chat (the gear icon) to open the Agent Customizations editor, then select the Skills tab. Chat: Open Customizations from the Command Palette opens the same editor. It is marked Preview.
Select New Skill (Workspace) or New Skill (User), depending on where you want to store the skill.
Select the location and enter a name for the skill.
Complete SKILL.md by filling in the YAML frontmatter and adding instructions in the body.
Optionally, add scripts, examples, or other resources to the skill's directory.

The docs start from this file:

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

A testing skill in the docs keeps SKILL.md for the procedure, test-template.js as a template, and an examples/ directory for scenarios. Reference any additional files from SKILL.md or the agent will not pick them up. Use a Markdown link or a #file: reference with a path relative to SKILL.md, such as [test template](./test-template.js) or #file:./test-template.js. For your user home folder, use ~ or start a path with ~/, such as #file:~/skill-resources/test-template.js. Use Unix-style / separators so the skill stays portable across operating systems.

You can also generate the file. Type /create-skill in chat and describe the skill. The docs' example is "a skill for running and debugging integration tests". The agent asks clarifying questions and generates a SKILL.md file with the directory structure, instructions, and frontmatter. After a multi-turn debugging session, you can ask it to create a skill from how you just debugged the issue. Generate Skill in the Agent Customizations editor dropdown does the same job from the editor.

Write frontmatter that will actually load

SKILL.md is Markdown with YAML frontmatter. Two fields are required.

name is a unique identifier. Only lowercase letters, numbers, and hyphens are allowed, as in webapp-testing. Do not use slashes, colons, dots, or namespace prefixes. It must match the parent directory name, and the maximum is 64 characters. Names with invalid characters cause the skill to silently fail to load.

description must say what the skill does and when to use it. Be specific about both capabilities and use cases, because Copilot uses that text to decide when to load the skill. The maximum is 1024 characters.

Optional fields:

argument-hint is hint text shown in the chat input when the skill is invoked as a slash command, for example [test file] [options].
user-invocable controls whether the skill appears in the / menu. It defaults to true. Set it to false to hide the skill from that menu while still allowing the agent to load it automatically.
disable-model-invocation controls automatic loading. It defaults to false. Set it to true to require manual invocation through the / command only.
context controls how the skill is loaded. It defaults to inline, which adds the instructions to the parent agent's context. Set it to fork to run the skill in a dedicated subagent and return only the final result. Forked skill context is experimental and might change or be removed. To use it, enable github.copilot.chat.skillTool.enabled.

When a skill is distributed through a plugin, the plugin name is automatically used as a command prefix, for example /my-plugin:test-runner. Do not add namespace prefixes to name. Prefixes such as myorg/skillname or myorg:skillname cause the skill to silently fail to load.

The body should describe what the skill helps accomplish, when to use it, the steps to follow, examples of expected input and output, and references to any included scripts or resources.

Invoke a skill from chat

Skills are available as slash commands in chat, alongside prompt files. Type / in the chat input, then select a skill. You can add extra context after the command. Documented examples are /webapp-testing for the login page and /github-actions-debugging PR #42.

Access depends on the two optional flags:

Omit both, and the skill is a slash command and can be auto-loaded. That is the general-purpose case.
user-invocable: false hides the slash command but still lets Copilot load the skill when it is relevant.
disable-model-invocation: true keeps the slash command and turns off automatic loading, for skills you only want on demand.
Both set means the skill is disabled: no slash command, and no automatic load.

Copilot loads content in three steps. It reads name and description from the frontmatter. If you ask for something that matches the description, or you type the slash command, it loads the SKILL.md body. It then reads other files in the skill directory only when the instructions reference them. A file that is not referenced is not loaded, which is why you can install many skills without putting all of them into context. A skill that opts into a forked context follows the same discovery step, but its instructions and file reads stay in a separate subagent. Only the final result is returned to the parent agent.

Contribute a skill from an extension

Extensions contribute skills with the chatSkills contribution point in package.json. The path must point to a directory that contains a SKILL.md file, following the Agent Skills specification. In that contribution, the path property must point to the corresponding SKILL.md file. Copy the registration object from the Agent Skills documentation rather than retyping it. The directory name must match the name field. If it does not, the skill is not loaded.

The required folder structure is:

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

The contributed SKILL.md uses the same format as a project or personal skill. For a directory named skills/my-skill/, the name field must be my-skill.

Add a skill someone else wrote

The docs point to community collections in the github/awesome-copilot repository and the anthropics/skills repository, plus skills bundled in agent plugins. To use a shared skill, browse the available skills, copy the skill directory to your .github/skills/ folder, review and customize SKILL.md, and optionally modify or add resources. Review shared skills before using them. If a skill runs scripts, VS Code's terminal tool still applies its own approval controls.

The same skill is intended to work with GitHub Copilot in VS Code (chat and agent mode), GitHub Copilot CLI, the GitHub Copilot app, Copilot cloud agent, and OpenAI Codex through Agent Host (Experimental). Check supported locations for each experience before you assume every optional field travels with the folder.

Next step: in chat, type /skills and create a workspace or user skill, or confirm that an existing SKILL.md is already listed. If you are contributing the skill from an extension, match the directory name to the name field and copy the chatSkills registration from the official Agent Skills page so path points at that SKILL.md.

Sources

Use Agent Skills in VS Code