Sometime last year (October 16, 2025), Claude announced the launch of agent skills.
At the time, I didn’t pay much attention, and I don’t think I was alone. Unless you were deep in the Claude ecosystem, it mostly flew under the radar. Even as someone actively using AI tools, it felt like one of those announcements you bookmark mentally and move on from.
Fast forward to recently, and suddenly, skills are everywhere. Not just blog posts or announcements, but real usage. People are building with them, companies are setting them up, and engineers are talking about them like they’ve been doing this forever. That’s when I decided to stop skimming and actually start testing things, reading through examples, and paying attention to how people were using skills in the wild.
And honestly, it got really interesting, really fast. Earlier this month, Vercel released agent skills for React and related tooling.
What stood out was how opinionated and solid the knowledge felt. This wasn’t a generic assistant. This felt like accumulated experience from people who deeply understand the ecosystem being handed directly to an agent.
Then Vercel launched skills.sh, basically an index of agent skills. Almost like an npm registry, but for expertise instead of packages.
That’s when it clicked for me. We already have thousands of skills. Across frontend, backend, DevOps, video, infrastructure, tooling, and all kinds of domains. This isn’t some early experiment anymore. This is a growing layer of shared knowledge that agents can tap into.
One that really caught my attention was Remotion. Remotion has always been a powerful tool for making videos programmatically, but a few days ago, they introduced an official agent skill, and things went a little wild.
The announcement drew massive attention; people started creating and sharing videos almost immediately, and the community jumped in hard. I even ended up creating a video myself just to explain what was happening.
At that point, it felt like a lot of separate things I’d been seeing over the past couple of years suddenly lined up:
- We now have AI agents.
- We have instruction files like
CLAUDE.md. - We have MCP servers connecting agents to real tools and external context.
- And now we have agent skills that package deep, domain-specific expertise.
If you’ve been watching all of this unfold, you’ve probably had the same question I did: how do these pieces actually fit together?
That’s what this post is about. These are just some thoughts, based on what I’ve noticed, tested, and slowly started to understand.
We’ve been trying to give agents context since 2023
When ChatGPT launched in 2022, the immediate focus was on capability. It could write code, explain concepts, generate text, and reason through problems.
Very quickly, people started wrapping that capability into “agents”, which are tools meant to do real work instead of just answering questions.
That led to agents for coding, research, finance, spreadsheets, data analysis, and more. Over time, it became normal to think in terms of which agent you needed for a task.
But once you tried to use these agents seriously, a pattern showed up. The models were capable, but they lacked context.
They didn’t know how a specific project was structured, what conventions a team followed, which files were sensitive, which tools were allowed, or what decisions had already been made. As tasks became more complex, prompting got longer and more repetitive. You had to keep explaining the same background just to avoid obvious mistakes.
This is where instruction files started to appear.
Instruction files helped, but only in one direction
The idea behind instruction files was that instead of repeating context in prompts, write it down once and let the agent read it every time.
Claude popularized this pattern with CLAUDE.md. Other tools followed with similar files that describe project structure, workflows, coding standards, and expectations. The exact filename varies, but the intent is the same.
These files made agents noticeably better at working inside real projects. They reduced misunderstandings, aligned output with team practices, and made collaboration easier, especially when multiple people were using AI on the same codebase.
But instruction files mainly solve internal context. They explain how things work inside a project, not how to interact with the outside world. They don’t give agents access to live systems, tools, APIs, or data. They just describe them.
That limitation became obvious as people tried to push agents further.
MCPs extended context beyond the project
MCPs (Model Context Protocol servers) address a different problem: providing agents with structured access to external tools and resources.
Instead of copying data into prompts or writing custom integrations for every tool, MCPs enable agents to query systems (repositories, filesystems, APIs, internal services) directly in a controlled way.
This is an example of my conversation with Claude after setting up an MCP server, exposing the Kinsta API:
This matters because it changes how agents operate. They no longer rely entirely on what the user pastes into a chat. They can retrieve information when needed and act based on real data rather than approximations.
At this point, agents have internal context (instruction files) and external context (MCPs and tool access), yet something is still missing.
Because even with full access to context and tools, agents still make poor decisions in specialized domains. They know what exists, but not necessarily how experts think in that space. That’s where skills fit in.
They aren’t about access or memory. They’re about encoding expertise, the assumptions, best practices, and hard-earned knowledge that usually live in people’s heads or scattered docs.
And that’s why, for me, skills are the piece that finally makes the rest of this ecosystem click.
Agent skills introduce expertise
Once you separate context from expertise, skills start to make a lot more sense. Instruction files explain how a project works, MCPs give agents access to tools and external systems, but neither of those tells an agent how an expert would approach a problem in a specific domain.
That gap shows up pretty clearly in practice. You can give an agent full access to a React codebase, your repo structure, your APIs, even your deployment setup — and it will still make questionable decisions if it doesn’t understand the culture and trade-offs of that ecosystem.
Things like what patterns are considered idiomatic, what should be avoided, and what “good” actually looks like.
Skills are an attempt to encode that layer. They package domain knowledge in a way that agents can consistently apply. Not just “here’s the API” or “here’s the folder structure,” but “this is how people who work on this every day think about problems.”
That’s why the Vercel example stood out to me. I watched a talk by folks at Anthropic where they argued that instead of creating more specialized agents, we should focus on building skills.
At first, it sounds counterintuitive. We’ve spent the last few years naming and shipping agents for everything. But once you think about it, the current generation of agents is already general and capable enough.
The bottleneck isn’t intelligence, but specialization. Skills let you take a general agent and make it behave like a domain expert without fragmenting the ecosystem into dozens of narrowly-scoped agents. You don’t need a “Remotion agent” or a “React agent” or a “DevOps agent.” You need one capable agent with the right skills loaded.
That’s a much cleaner mental model.
What skills actually look like in practice
One thing that surprised a lot of people (including me) is how simple skills are under the hood.
They’re mostly markdown files. Structured text that explains assumptions, workflows, constraints, and best practices. There was a comment I saw under one of the talks that summed it up well:
It’s funny, but it’s also accurate. A skill is basically a folder, and the entry point is almost always a SKILL.md.
The first thing that matters is the frontmatter. At the top of SKILL.md there’s YAML frontmatter (the --- block). This is where you put the name and description. In practice, this is what the agent uses to decide whether the skill applies at all. So the description is not “marketing text”, it’s the matching logic in plain English.
Then comes the body. Everything after the frontmatter is just Markdown. There aren’t strict formatting rules, but the spec recommends keeping it practical: steps, examples, edge cases, “do this / don’t do this”, and the constraints that matter in the real world.
It’s also important to know that the agent typically loads this full body only after it’s decided the skill should activate.
Once a skill grows beyond a few pages, you don’t keep stuffing everything into SKILL.md. The spec explicitly recommends splitting longer content into referenced files (bundled resources) and pointing to them from the main skill. That’s how you end up with a clean SKILL.md plus a bunch of focused docs inside the skill folder.
Skills work because they’re explicit, opinionated, and readable both by humans and agents. Once you see that, it becomes obvious why instruction files, MCPs, and skills aren’t competing ideas.
How these pieces fit together as one workflow
What made all of this finally make sense to me is realizing that these ideas didn’t appear randomly. They solve different problems at different layers, and when you line them up, the workflow becomes pretty clear.
It usually starts with instructions, then comes context beyond the repo, which is where MCPs fit. And finally, skills sit above everything else. When you put together, the flow looks something like this:
- The agent reads instructions to understand the project and expectations
- It uses MCPs to interact with real tools and data
- It applies skills to reason and make decisions like a domain expert
At that point, you’re no longer trying to “build the right agent” for every task. You’re using a capable general agent and shaping its behavior through context, access, and expertise.
That’s why the “stop building agents, start building skills” idea resonated with me. It’s not about reducing ambition. It’s about realizing that the agents we already have are powerful enough.
And once you see it that way, a lot of the recent changes in the ecosystem stop feeling disconnected. They start to look like different parts of the same system, finally snapping into place.
For now, this is enough…
