Agent skills are folders of instructions, scripts. And resources that an AI coding agent loads on demand, per the VS Code docs.
The folder gets a name, a SKILL.md file, and a home in your repo.
That single file now works across 40+ agent platforms. So you’re not writing prompts anymore. You’re writing workflow code you can diff, review, and gate.
And that’s the entire argument.
Prompts rot in scrollback. Skills sit in version control.
Agent Skills vs Custom Instructions: What’s the Difference
Start with the definitions.
Because they’re shorter than you’d expect. VS Code’s documentation calls Agent Skills “folders of instructions, scripts. And resources that AI agents can load when relevant to perform specialized tasks.” Claude’s docs say each skill packages instructions, metadata. And optional resources like scripts and templates. And that the agent “uses automatically when relevant.” Their phrase for the payoff: skills “turn a general-purpose agent into a specialist.”
The real split is scope. Custom instructions are always applied, or applied through glob patterns. Skills load on demand for task-specific work. Claude draws the same line, noting that unlike conversation-level prompts for one-off tasks, skills load “so you don’t have to repeat the same guidance across conversations.”
Think of a repair shop.
Custom instructions are the rules taped to the bay wall, applying to every job that rolls in, including the oil change that never needed them.
A skill is the torque-spec card you grab only when the truck’s actually on the lift. Always-on instructions tax every single request whether they help or not; an on-demand file pays its way only when the task matches.
There’s a second difference people miss. Per the VS Code comparison, custom instructions primarily define coding guidelines, while skills can carry scripts, examples, and other resources.
Guidelines tell an agent what good looks like.
A skill hands it the tooling to get there.
SKILL.md Runs on 40+ Agent Platforms
Portability is where this stopped being a vendor feature. Agent Skills are described as an open standard working across multiple agents: GitHub Copilot in VS Code, GitHub Copilot CLI, the GitHub Copilot app. And the experimental OpenAI Codex integration. The MassGen docs go wider, calling SKILL.md “an open standard supported by 40+ agent platforms” and naming Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, Gemini CLI, Goose. And Amp. Convex frames it from the builder’s side: “portable packages of instructions and workflows that teach AI coding agents how to perform specialized tasks.”
Now the catch, and it’s in the fine print of the VS Code docs themselves.
Skills travel across skills-compatible agents, “but supported locations and optional features vary by agent.” The instructions move; the host’s guarantees don’t. A skill leaning on an optional feature one agent honors and another ignores will half-work. And a half-working instruction is worse than an absent one, given that it looks fine at a glance. Load a new skill into both of your agents before you trust it in either.
Even with that, it’s the cheapest lock-in escape this market has offered. Your commitment shifts from a model subscription to a folder of markdown. Markdown, by the way, has now outlived every fancier format sent to replace it, which quietly amuses me. You can audit it with your eyes.
Reviewable Agent Workflows, Not Prompt Tips
The community collections are what turn this into an engineering practice. One GitHub collection holds “the 11 workflows I use across projects with Codex and Claude Code, rewritten as reusable instructions”. Debugging, adversarial review, bounded improvement loops, research, collaboration, Git hooks. And AEO. A second lists 34 skills, 2 agents, and config examples for software-development workflows, ready to install.
Read what’s encoded in those workflows.
The critical-adversarial-review skill is “independent review tied to an exact revision and reproducible defects.” The gauntlet-loop repeats build, critique. And regression rounds “with an acceptance bar.” The quality-gates workflow builds gates that “measure the intended behavior and reject a deliberately broken control.” Evidence-driven-debugging traces a reported failure “through the real data and runtime path,” and source-backed-research demands traceable sources and explicit uncertainty.
That’s process engineering.
Each workflow names a procedure and attaches a bar the procedure can fail.
Here’s the dividing line as I see it: a prompt is advice, a workflow is advice with a pass condition.
Once agent instructions live in a repo, review stops meaning “I skimmed the output” and starts meaning “I read the diff of the rules that produced it.”
Same property makes third-party skills survivable.
An installed skill is a set of instructions injected into an agent that can touch your repository, and popularity isn’t vetting.
Treat every skill like a dependency. Read it before you run it, re-read the diff when it updates. Nobody’s doing that vetting for you.
How to Write Your First Skill (SKILL.md)
The how-to is short enough to memorize:
1. Pick the task you re-explain to your agents most often.
2. Write it as a folder. A SKILL.md up front, scripts alongside, and the acceptance bar stated in plain text. Don’t skip the bar; without it you’ve written a prompt, not a workflow.
3. Commit it next to the code it governs, and review the diff like any pull request.
4. Load it into a second agent before you depend on it in the first.
That’s the whole loop. Step 2 is the one that earns snippet space, as the acceptance bar is what separates a skill from a sticky note.
If you’d rather start from vendor shelves, they exist. Convex ships ready-made skills for common workflows like setting up auth, designing a schema. And running migrations. Anthropic ships pre-built skills for PowerPoint, Excel, Word, and PDF document tasks. Those handle the generic work. The highest-return skills are still the ones nobody can write for you, since they encode what actually breaks in your repos.
Agent Skills for Solo Developers: Where to Start
Solo operators get more out of this layer than the enterprises writing the docs. Your migration routine, your review ritual, your “check this before deploy” list. Right now they live in your head or in chat scrollback, where they rot. Written as skills, they become artifacts every future agent run inherits and any future collaborator can read. Institutional memory you can commit.
Resist collecting 34 skills on day one.
Write three of your own encoding your real failure modes. A small set you’ve read beats a large set you haven’t.
The shift underneath all of it: prompts are scrollback, skills are source. Put your agent instructions in version control with acceptance bars and revision anchors. And you stop being a prompt whisperer and start being the engineer of the thing doing the work. The 40+ platform count says the format has gravity. The collections above say what to build with it.
So open the VS Code agent skills docs or the Claude skills overview, write one skill for the workflow you keep re-typing, and commit it.
Then read the diff and ask whether you’d approve your own instructions. If the answer’s no, you’ve found the first thing worth fixing. Fix it, commit again, repeat until the answer’s yes.
That’s the job now.
FAQ: Agent Skills
What is SKILL.md?
It’s the markdown file at the front of an agent skill folder. The part agents read to know what the skill does and when to load it. The MassGen docs call SKILL.md “an open standard supported by 40+ agent platforms.”
How are agent skills different from custom instructions?
Custom instructions are always applied, or applied through glob patterns, and mostly define coding guidelines. Skills load on demand for task-specific work and can carry scripts, examples, and other resources, not just text.
Are agent skills portable across platforms?
Yes, across skills-compatible agents. With a caveat from the VS Code docs: “supported locations and optional features vary by agent.” Test a new skill in both of your agents before trusting it in either.
Are third-party skills safe to install?
Treat them like dependencies. An installed skill injects instructions into an agent that can touch your repository, and popularity isn’t vetting. Read it before you run it, and re-read the diff when it updates.
Do I need to write my own skills?
Pre-built ones cover generic work (Anthropic’s document skills, Convex’s auth and migration skills). The highest-return skills encode what actually breaks in your repos, and nobody else can write those.
Sources
– VS Code — Agent Skills documentation
– Claude — Agent Skills overview
– MassGen — Skills documentation
– Convex — Agent Skills
– rubenmarcus/agent-skills collection
– hjewkes/agent-skills collection
