Skip to content

VS Code Agent Skills — the complete guide (Burke Holland)

A Microsoft DevRel-led walkthrough of the Agent Skills format and how it landed in VS Code's GitHub Copilot extension. The video doubles as an authoring tutorial and a comparison guide against adjacent customisation primitives.

Video

Source: https://www.youtube.com/watch?v=fabAI1OKKww

Transcript notes

Key beats from the talk:

  • What a Skill is: a directory whose only mandatory file is SKILL.md — YAML frontmatter (name, description) + a Markdown body, optionally accompanied by scripts/, references/, assets/.
  • Progressive disclosure in three levels: (1) the YAML frontmatter (~100 tokens) is always in the system prompt; (2) the body of SKILL.md is loaded only when the description matches the user's task; (3) bundled files load on demand when the body links to them.
  • PDF parsing walkthrough: live build of a skill that converts a PDF, structures the extracted text into Markdown, and writes the result back to disk — illustrating the body + helper-script pattern.
  • Decision matrix vs adjacent primitives: Custom Instructions are always-on house rules; Prompt Files (.prompt.md) are named one-shot slash commands; Custom Agents are role/identity boundaries with their own tool list; Skills sit between Instructions and Agents — auto-discovered, multi-step, asset-bundled.
  • Authoring pitfalls: vague trigger descriptions cause under-triggering; over-broad descriptions cause spurious activation; a name that doesn't match the parent directory makes the skill silently fail to load.
  • VS Code paths: Skills are discovered under project-level .github/skills/, .claude/skills/, .agents/skills/ and personal ~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/.

Synthesis

Agent Skills are a folder-based capability format introduced by Anthropic on 16 October 2025 and published as an open, cross-platform standard on 18 December 2025. A Skill is a directory with one mandatory file — SKILL.md, containing YAML frontmatter and a Markdown body — and optional scripts/, references/, and assets/ subfolders. Required frontmatter is name (kebab-case, max 64 chars, must match the parent directory) and description (max 1024 chars, describing both what the skill does and when to use it). The optional fields license, compatibility, metadata, and the experimental allowed-tools are standardised in the open spec at agentskills.io, while individual tooling vendors layer on host-specific fields (VS Code recognises argument-hint, user-invocable, disable-model-invocation, and experimental context: fork for sub-agent execution).

The defining design choice is progressive disclosure across three levels. Level 1 — the YAML frontmatter — is always loaded into the agent's system prompt and represents roughly a hundred tokens per skill; the agent consults description to decide whether the skill is relevant. Level 2 — the body of SKILL.md — is read into context only when the description matches the active task. Level 3 — bundled files such as reference markdown, scripts, or templates — are loaded only when the body explicitly references them, typically via filesystem or code-execution tools. The practical consequence is that a workspace can install dozens of skills without paying a continuous context tax, which is what makes the format attractive to host an extension as heterogeneous as VS Code's Copilot.

Microsoft shipped native Agent Skills support in GitHub Copilot for VS Code in January 2026 and announced default-on rollout for February 2026, with the same support extending to the Copilot CLI and Copilot cloud agent. VS Code scans project paths (.github/skills/, .claude/skills/, .agents/skills/) and personal paths (~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/), so the same skill directory works whether the user invokes it through Claude Code or Copilot. Independent trade press confirmed that this was a deliberate Microsoft strategy of treating Claude artefacts — CLAUDE.md, .claude/rules, agents, skills, hooks — as first-class citizens in VS Code rather than reinventing parallel formats.

The decision matrix the video lays out is now reasonably crisp. Custom Instructions handle always-on house rules and coding-style preferences (.github/copilot-instructions.md, AGENTS.md); they have no logic and load every turn. Prompt Files (.prompt.md) are manually-invoked one-shot slash commands — useful for repeatable single-shot tasks but unable to ship bundled assets. Custom Agents are role personas with their own tool allowlist and identity, heavyweight relative to a single task. Skills are auto-discovered multi-step workflows that can ship scripts, reference docs and templates; they sit between Instructions and Custom Agents in weight, and unlike Prompt Files they're triggered by an LLM judging the description against the task. MCP servers, separately, sit a layer below all of this and provide the external-data and tool-invocation plumbing that any of the above can call into. Anthropic's own framing — "MCP is the kitchen; Skills are the recipes" — captures the layering cleanly.

The dominant authoring pitfall, repeated across Anthropic's docs and the talk, is the description field. Imperative phrasing ("Use this skill when the user asks to extract structured data from a PDF") outperforms passive descriptors ("Helps with PDFs"). Anthropic's skill-creator reference skill ships an improve_description.py optimiser that iterates over candidate descriptions and measures triggering accuracy, which is a strong hint about where the load-bearing engineering work sits. Other common pitfalls flagged in the talk and in subsequent community write-ups: a name that doesn't match the parent directory (silent load failure), namespace prefixes like org:name (also silent failure in Copilot), and SKILL.md bodies past roughly 500 lines that bloat context once triggered — the recommended fix is to push detail into references/*.md files and link to them from the body.

Anthropic's reference anthropics/skills repository (around 132k stars by May 2026) is the canonical example library, shipping pdf, docx, xlsx, pptx (the document-skills bundle that powers Claude's file-generation features) plus skill-creator, mcp-builder, webapp-testing, brand-guidelines, algorithmic-art, and others. GitHub's github/awesome-copilot aggregates the Copilot-side community equivalent. Together they form a working corpus for anyone learning the format, and they're a more reliable starting point than hand-rolled examples.

The strategic takeaway from the talk is that Agent Skills succeeded because the spec is small — folder, Markdown, YAML — and piggy-backs on filesystem affordances every agent already has, then was opened as a standard before competitors could fragment the field. Microsoft's January 2026 adoption is the strongest signal so far that the format is portable in practice rather than just in principle, and the decision boundary versus adjacent primitives is now stable enough that teams can pick the right primitive for the job without much guesswork.

Changelog

  • 2026-05-10 — Scaffold created from https://www.youtube.com/watch?v=fabAI1OKKww (Type C, awaiting transcript; flagged "Good")
  • 2026-05-11 — Synthesised from transcript + deep research; confidence pending → 92 (Type C transcript + 4 Type A primary sources + 2 Type B trade press); related_pages updated from anthropic-agent-skills (tombstoned) to claude-agents, github-copilot-agents, agents-overview