If you've been building anything with AI agents lately, you've probably stumbled into a familiar loop. You write a great prompt. It works. You tweak it. You save it somewhere. Maybe you paste it into a markdown file. Maybe you shove it into your project repo so your teammate stops asking you for it.
Congratulations. You were already using skills before anyone called them that.
So what actually are skills?
Let's cut through the noise. A skill is basically a file, usually markdown, that gives an AI agent specific knowledge or instructions for a particular task. Think of it like a cheat sheet you'd hand to a new coworker on their first day. "Here's how we do Stripe payments. Here's our brand voice. Here's how we structure our API routes."
That's it. That's the concept.
Now, the idea itself isn't new at all. Early tools like AutoGPT and BabyAGI were already doing versions of this, stuffing prompts and constraints into .md and .yaml files. Cursor took it further with rules you could set at different levels, which was precise but honestly created more busywork for developers. And then Claude Code came along with the claude.md file, which gave you a central place to dump project context.
Everyone was kind of doing the same dance, just in different shoes.
What Claude Skills actually did was give this whole practice a proper name. They formalized it. And because Claude Code had serious momentum at the time, the convention stuck. Sometimes the most important thing isn't inventing something new. It's just agreeing on what to call the thing that already exists.
Why you should actually care
Okay, but why not just keep doing what you were doing? Why bother with the "skills" framing at all?
Three reasons, and they're more practical than you might think.
Your AI's knowledge has an expiration date
Models get trained, and then their knowledge freezes. Everything after that cutoff? Gone. And technology moves fast. Terrifyingly fast, actually. So your agent might confidently use a deprecated framework or suggest a pattern that was best practice six months ago but is now considered an anti-pattern. Skills let you inject current, accurate knowledge without waiting for the next model update.
Web search is slow and expensive
Sure, you could have your agent Google things every time it needs help. But that burns tokens, takes time, and sometimes the agent goes on a wild goose chase through Stack Overflow threads from 2019. A well-written skill is like having the answer already sitting on your desk. Local lookup. No parsing random websites. No waiting.
Context is precious real estate
This is the one that sneaks up on you. You start a project, load up your system prompt, add some MCP tools, throw in a massive claude.md file, and suddenly you've eaten through half your context window before writing a single line of code. That leads to context rot. The model starts compacting and summarizing to fit everything in, and you slowly lose the sharp edges of your instructions. A well-crafted skill like this Stripe best practices one gives your agent exactly what it needs without the bloat.
And skills solve the context problem because they load just in time. Your agent pulls them in only when they're relevant, not upfront like everything crammed into a system prompt.
The "just in time" loading is probabilistic. It works maybe 70 to 80 percent of the time on its own. The other 20 to 30 percent? You just ask the agent to use the skill. Not perfect, but honestly pretty good for something that saves you this much hassle.
Where do they actually live?
This part still isn't fully standardized across every tool, which is a little annoying. But three patterns have emerged that most people gravitate toward.
Project-level skills sit in a subdirectory of your project. This is my go-to approach most of the time. They travel with your Git repo, so your whole team gets the same skills. The trade-off is you need to add them to each project individually. Small price to pay.
Global skills get installed at the user level, so every project on your machine has access. These make sense for broadly useful things like a frontend design skill you always want available. But be careful here. If you have project-level skills for brand-specific UI or design patterns, a global frontend design skill could conflict or get pulled in instead of your project's version. Think about scope before going global.
Plugin-based skills come bundled with tools or extensions and usually get managed through your agent's command line. Think of these like packages you install and uninstall as needed.
For Claude Code specifically, the paths look like this:
- Global:
~/.claude/skills/<skill-name>/SKILL.md - Project:
<project-root>/.claude/skills/<skill-name>/SKILL.md
Other agent tools like Cursor, Codex, or Amp have their own conventions, so check their docs for the specifics. For more on Claude's approach, check out the official skills documentation and Anthropic's complete guide to building skills.
Getting skills installed
You've got options here, and none of them are complicated.
The simplest approach? Just copy the file. Create a .skills/ directory in your project, drop the markdown file in, and you're done. No package manager, no CLI magic. Just a file in a folder.
If you want something more streamlined, sites like skills.sh have popped up to help you browse and install skills with less friction. And some agent tools have built-in commands for installing skills directly from their interfaces.
There are already thousands of skills out there covering everything from Stripe integration to database migrations. And creating your own is literally as easy as writing a text file. If you can write a README, you can write a skill.
The part nobody wants to talk about
Here's where I need to get serious for a second.
Skills are powerful precisely because they can inject instructions directly into your agent's workflow. And that same power makes them genuinely dangerous if you're not careful.
When you install a skill from the internet, you're essentially giving it influence over what your agent does on your machine. If you run your agent with permissions disabled (which, let's be honest, a lot of us do for convenience), that skill has a pretty long leash. There have already been documented cases of skills containing hidden prompt injections, non-visible characters designed to manipulate behavior, and outright malicious instructions.
This isn't theoretical. It's happening right now. In just the last few weeks, multiple security researchers have flagged real examples of compromised skills circulating in the wild:
So please, before you install a skill you found online, actually read it. The whole thing. Look for anything suspicious. Check for hidden characters. Make sure you trust the source. It takes five minutes, and it could save you from a very bad day.
The bottom line
Skills aren't revolutionary technology. They're a smart convention wrapped around something developers were already doing instinctively. But that convention matters. It gives us a shared language, a predictable structure, and a way to keep our agents sharp without drowning in bloated prompts or expensive API calls.
Use them. Create your own. Share them with your team. Just be thoughtful about which ones you trust.
Because at the end of the day, the best tool is the one you understand well enough to use safely.