Skill Creator

Create concise, high-signal skills with clear triggers, reusable resources, and progressive disclosure.

VS Code Copilot File Types

File Type	Path	Purpose
Always-on instructions	`.github/copilot-instructions.md`	Project-wide rules loaded in every chat
Scoped instructions	`.github/instructions/*.instructions.md`	Rules applied based on `applyTo` glob or description
Reusable prompts	`.github/prompts/*.prompt.md`	Slash commands for specific tasks
Custom agents	`.github/agents/*.agent.md`	Named agents with tools, model, and handoff config
Project skills	`.github/skills/<name>/SKILL.md`	On-demand capabilities with scripts and resources
Personal skills	`~/.copilot/skills/<name>/SKILL.md`	User-level skills across all workspaces

SKILL.md Format

yaml

---
name: skill-name                    # REQUIRED — must match directory name exactly
description: >                      # REQUIRED — max 1024 chars; be specific about WHEN to trigger
  What it does and when to use it.
argument-hint: "[input hint]"        # Optional — shown in / menu
user-invokable: true                 # Optional — show in / menu (default: true)
disable-model-invocation: false      # Optional — prevent auto-loading (default: false)
---

# Skill Body
Detailed instructions here...

Rules for name:

•Must be lowercase, using hyphens for spaces
•Must match the parent directory name exactly
•Maximum 64 characters
•Example: directory dj-tag-editor → name: dj-tag-editor

.instructions.md Format

yaml

---
description: "Short description for hover display"
applyTo: '**/*.py'          # Glob pattern for auto-application
---

# Instructions

.prompt.md Format

yaml

---
description: "What this prompt does"
agent: 'agent'              # 'agent' for agentic mode
tools: ['search', 'edit', 'problems', 'read']
argument-hint: "${input:variableName}"
---

# Prompt body
Your instructions here with ${input:variableName} placeholders.

.agent.md Format

yaml

---
description: "What this agent specialises in"
name: My Agent
tools: ['search', 'edit', 'execute', 'read', 'problems']
model: 'Claude Sonnet 4.5'
target: 'vscode'
infer: true
---

# Agent Instructions

Writing Effective Skill Descriptions

The description field is what VS Code reads to decide whether to activate a skill. Make it:

•Specific about triggers: include keywords users are likely to say
•Specific about capabilities: list the exact technologies and tasks covered
•Under 1024 characters

Good example:

code

Generate and review Playwright Python tests using role-based locators and web-first assertions. Use when writing UI tests, end-to-end tests, fixing flaky selectors, or setting up Pytest fixtures for web automation.

Weak example:

code

Testing skill for Python.

Progressive Disclosure Design

VS Code loads skills in three levels:

•Discovery — reads only name + description (always loaded, lightweight)
•Instructions — loads SKILL.md body when request matches description
•Resources — loads additional files referenced in body (scripts, examples)

Design for this: put the most critical "when to use" context in the description, not just the body.

Directory Structure Best Practices

code

.github/
├── copilot-instructions.md          # Always-on project rules
├── instructions/
│   └── python-rules.instructions.md # Scoped: applyTo **/*.py
├── prompts/
│   └── refactor-module.prompt.md    # Slash: /refactor-module
├── agents/
│   └── my-specialist.agent.md       # @my-specialist
└── skills/
    └── my-skill/
        ├── SKILL.md                 # Required
        ├── helper-script.sh         # Optional resources
        └── examples/                # Optional examples

Common Mistakes

Mistake	Fix
`name` in SKILL.md doesn't match directory	Rename either the file or directory
Description is too vague	List specific technologies, tasks, trigger phrases
Body content in description field	Move detailed instructions to the body
Missing `applyTo` in instructions file	Add glob pattern or rely on semantic matching
Agent handoff references non-existent agent	Create the target `.agent.md` file