| name | skill-creator |
| description | Guide for creating effective VS Code agent skills, custom instructions, prompts, and agents. Use when building new SKILL.md files, writing .instructions.md files, defining .prompt.md or .agent.md files, or setting up a .github/ Copilot directory structure. Covers frontmatter schemas, path requirements, progressive disclosure, naming conventions, and VS Code discovery behaviour. |
| argument-hint | [skill or file type to create, e.g. 'a skill for Python linting'] |
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
---
name: skill-name
description: >
What it does and when to use it.
argument-hint: "[input hint]"
user-invokable: true
disable-model-invocation: false
---
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
---
description: "Short description for hover display"
applyTo: '**/*.py'
---
.prompt.md Format
---
description: "What this prompt does"
agent: 'agent'
tools: ['search', 'edit', 'problems', 'read']
argument-hint: "${input:variableName}"
---
Your instructions here with ${input:variableName} placeholders.
.agent.md Format
---
description: "What this agent specialises in"
name: My Agent
tools: ['search', 'edit', 'execute', 'read', 'problems']
model: 'Claude Sonnet 4.5'
target: 'vscode'
infer: true
---
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:
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:
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
.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 |
