skill-creator

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

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

# Instructions

.prompt.md Format

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

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

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:

1. Discovery — reads only name + description (always loaded, lightweight)
2. Instructions — loads SKILL.md body when request matches description
3. 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