Using Agent Skills in VS Code for reusable workflows and local context

This is Part 2 of the AI in VS Code series. For the first article, see Using AGENTS.md in VS Code with clear rules and useful context.

Introduction

Once you have AGENTS.md in place, the next question appears quickly: what should live there, and what should be pulled out into a skill?

That is also the point where it helps to be deliberate. Once you realize that skills can hold instructions, scripts, references, and templates, it becomes tempting to move every useful rule into one. A few pitfalls are worth avoiding:

• generic skills that are too vague to trigger reliably
• project skills that are written as if they were portable even though they only make sense in one repository

The interesting part of skills in VS Code is not that they are more powerful prompts, but that they give you a portable way to package capability. That changes the design problem.

With AGENTS.md, the question is usually: what truth should this repository state explicitly for every task?

With skills, the question is different: what reusable capability deserves its own package, and what local knowledge should stay tied to the project? That distinction matters more than the file format.

What VS Code actually supports

VS Code treats Agent Skills as directories with a SKILL.md file and optional bundled resources. It can discover them in repository locations such as .github/skills/, .claude/skills/, and .agents/skills/, and in corresponding user-level directories as well.

That matters because a skill is not just a Markdown note. It can carry extra material with it:

• instructions in SKILL.md
• reference documents
• helper scripts
• templates or other static assets

This is the practical difference from custom instructions. Instructions tell the model how to behave. A skill can also give it tools and context for doing a specific kind of work.

VS Code also supports two access patterns:

• explicit invocation through /skill-name
• automatic loading when the skill appears relevant

The loading model is more disciplined than it first looks. VS Code starts by seeing only the skill metadata, especially the name and description. If the skill looks relevant, it loads the SKILL.md body. Only then does it reach for bundled resources that the skill references.

That progressive loading model is important because it explains why many weak skills fail. The problem is often not buried deep in the instructions. The problem is that the skill description is too weak for the model to discover it in the first place.

Skills are an open format, not just a VS Code feature

This is the part I think many developers miss.

Agent Skills are not merely a VS Code customization trick. They follow the open Agent Skills format, and the specification is deliberately small.

At the format level, the required frontmatter is almost minimal:

• name
• description

There are optional fields such as license, compatibility, metadata, and an experimental allowed-tools, but the core idea stays simple: a skill is a directory with a SKILL.md file plus whatever bundled resources actually help.

That simplicity is a strength.

It means skills are not locked to one editor. VS Code can use them, but the format itself is broader than VS Code, which makes it much more plausible as a long-lived way to package reusable agent capabilities.

The description is the real trigger surface

If there is one practical lesson worth carrying forward, it is this: the description is not metadata fluff. It is the main discovery surface.

The model does not begin by reading your whole skill body and admiring your careful structure. It begins by seeing the name and description and deciding whether the skill is relevant.

Good descriptions do three things:

1. They say what the skill does.
2. They say when to use it.
3. They contain realistic trigger language that matches the kinds of requests a user will actually make.

A description like web testing helpers is not serious enough. A description like Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture screenshots, or inspect browser console logs. is much closer to what automatic discovery needs.

This is one reason skills should stay focused. A one-purpose skill is easier to describe accurately, easier to discover, and easier to improve when it under-triggers or over-triggers.

Where to get strong generic skills

For VS Code and Copilot users, the strongest general source is github/awesome-copilot.

That is not just because it has a lot of content, but because it is curated around the actual Copilot ecosystem: skills, agents, hooks, instructions, plugins, and a website with search and a learning hub. It is the closest thing to a high-quality generic catalog for this environment. If I were pointing someone to one starting place for reusable generic skills in VS Code, that would be it.

There is a second source worth studying for a different reason: anthropics/skills. I would not frame it as the default curated catalog for VS Code users, but as a strong reference library for how sophisticated skills can be structured. It is especially useful for patterns such as:

• progressive disclosure through references and scripts
• explicit verification loops
• richer bundled resources
• evaluation and iteration of skill quality

So the split is roughly this:

• awesome-copilot for curated generic skills that are close to the VS Code and Copilot experience
• anthropics/skills for stronger reference patterns and more ambitious examples

Skills versioning is mostly a packaging problem

This is one area where expectations can drift away from the actual format. The Agent Skills spec does not require a dedicated version field. If you want a version inside the skill, the cleanest place is usually metadata, because the spec explicitly allows arbitrary key-value metadata. But that does not mean every skill needs metadata.version.

In practice, versioning often lives outside the skill body:

• Git history
• repository tags
• release notes
• plugin manifests
• marketplace distribution

That is a better mental model than imagining every SKILL.md should behave like a package manifest. If a skill is distributed through a plugin or marketplace, version the distributable rigorously. If a local repository skill evolves alongside the codebase, Git history is often enough. Add an in-file version only when humans or tooling genuinely benefit from seeing it there.

Generic tech skills versus project-specific skills

This is the split that matters most in practice.

Generic skills should travel. If a skill teaches the agent how to test a local web application, review a UI, extract structured data from PDFs, or follow the current guidance for a framework, that can often be reused across many repositories. Those are portable capabilities.

Project-specific skills should tell the truth about one codebase. That includes things like:

• business-domain knowledge
• repository organization that is not obvious from code alone
• local validation workflow
• commit structure rules
• ADR or issue-linking conventions
• release or deployment policy

This is the same distinction the previous article on AGENTS.md touched from another angle. A local repository may have a perfectly reasonable commit skill, but that does not make it a good generic skill for strangers on the internet. It is usually a project policy packaged as a reusable local workflow. That does not make it less valuable. It just makes it local truth, not portable capability.

I think the cleanest rule is this:

• if the skill would still be useful after you stripped away the repository name, it might be generic
• if the skill becomes wrong or meaningless without repository-specific context, it belongs to the project

That sounds obvious, but it is a useful filter when deciding what is genuinely reusable and what should stay anchored to one project.

The human and AI structure still matters

The previous article argued for a two-layer shape:

• compact guidance for humans first
• richer rationale and edge-case context below it

That pattern applies to skills too, and in some ways it applies even better.

Humans still need fast scanning. They need to understand what a skill is for, when it should trigger, and what contract it expects them to maintain.

The agent still needs more than slogans. It needs the real workflow, the references, the scripts, the examples, the output shape, and the failure handling.

Skills are especially good at this because they do not force all of that detail into one giant file. The top of SKILL.md can stay readable, while deeper material lives in references/, scripts/, or other bundled files.

So the same design principle holds:

• keep the human-facing contract easy to scan
• keep the AI-facing detail close enough to use, but not jammed into the top of the file

That is the real value of the format. Not novelty. Structure.

What I would actually do in a repository

If I were setting this up in a real VS Code workflow, I would use three layers.

1. AGENTS.md for always-on repository truth.
2. Generic skills for portable technical workflows worth reusing elsewhere.
3. Local project skills for domain knowledge and workflow rules that should not pretend to be generic.

That gives each customization surface a real job.

It also helps avoid a common failure mode where AGENTS.md accumulates too many unrelated rules, while skills grow into large mixed-purpose bundles.

The goal is not to maximize the number of customization files. The goal is to make each one carry the kind of truth it is actually good at carrying.

Conclusion

The interesting thing about skills in VS Code is not that they let you write longer instructions. It is that they let you package reusable capability in a form that can travel.

That makes them more powerful than repository instructions, but it also raises the quality bar.

Weak descriptions do not trigger. Bloated skills do not age well. Project policy disguised as generic guidance does not really travel.

The best skills seem to share a few traits:

• narrow enough to describe clearly
• rich enough to reduce repeated work
• structured so humans can scan them and agents can apply them
• explicit about what is portable and what is local

That, to me, is the real skill design problem in VS Code.