What Are AI Agent Skills? Why They're So Useful
Skills teach Claude Code, Codex and Cursor to do a task your way. What they are, why they beat long prompts, and how they compare to plugins and MCP.
- Published
- Reading time
- 6 min read
Contents
If you use an AI coding agent, you've probably written the same long instructions more than once: how your project is organized, how you like commits written, which checks to run before you finish. Skills are the fix for that. You write the know-how down once, in a file, and the agent uses it whenever the task calls for it.
This guide explains what a skill is, why it's more useful than it sounds, and how skills compare to plugins, rules files and MCP connectors. The examples use Claude Code first, then Codex and Cursor.
Nil's note
The first skill I really used was Anthropic's frontend-design skill. I downloaded it, added it to this site's repository, and asked Claude to redesign DevPlainly with it. The difference was obvious: instead of the usual template look, it worked through a design plan, checked it against a list of "generic AI" patterns, and only then wrote code. Later I added Remotion's official skills to make short videos, and the same thing happened: the agent followed their best practices without me explaining them.
What a skill is
A skill is a folder with a SKILL.md file in it. The file starts with a short header and continues with instructions in plain Markdown:
---
name: article-checklist
description: Review a blog article before publishing. Use when the user asks to check, review or finish an article.
---
1. Check that the title is under 60 characters and starts with the keyword.
2. Check that there are 2 to 4 links to related articles.
3. Run the build and fix any error before saying the article is done.
The folder can also hold extra files the skill needs: longer reference documents, templates or scripts.
The format started with Anthropic's Agent Skills and is now an open standard, so the same folder works in several tools. Claude Code, OpenAI's Codex and Cursor all read SKILL.md files.
Why skills are so useful
1. You stop repeating yourself. The instructions you used to paste into every chat live in one file. Improve the file once and every future session benefits.
2. They don't fill up the context. At the start, the agent only sees each skill's name and description. It reads the full instructions only when a task matches. You can have many skills installed without slowing every conversation down, which matters because context is limited (see what tokens are).
3. They carry real expertise. A good skill is written by someone who knows the job: a design studio's process, a framework's best practices, your team's release checklist. The agent gets that knowledge instead of guessing.
4. They can bring tools, not just text. A skill can include scripts the agent runs, such as a validator or a generator, so the result is checked rather than just described.
5. They're easy to share. Put a skill in your repository and everyone who works on the project gets it. Package skills in a plugin and anyone can install them in one command.
Skills vs prompts, rules files, plugins and MCP
These terms get mixed up, so here's how they fit together:
| Term | What it is | When it's used |
|---|---|---|
| Prompt | What you type in one message | Once |
Rules file (CLAUDE.md, AGENTS.md, Cursor rules) | Project facts and conventions | Loaded in every session of that project |
| Skill | Instructions for one kind of task | Loaded only when the task matches, or when you call it |
| Plugin | A package that bundles skills and more (agents, hooks, MCP servers) | Installed once, then its parts work as usual |
| MCP connector | A connection to an outside tool or service, like a database or an issue tracker | When the agent needs data or actions from that service |
A simple way to remember it: rules files say what's true about your project, skills say how to do a task, plugins deliver them, and MCP connects the agent to other tools.
Skills in each tool
Claude Code
Claude Code looks for skills in ~/.claude/skills/ (yours, for every project) and .claude/skills/ (shared with everyone in the repository). It loads a skill automatically when its description matches what you ask, and you can call one directly by typing /skill-name. Plugins from a marketplace add more skills, available as /plugin-name:skill-name.
Codex
OpenAI's Codex reads skills from .agents/skills/ in your repository and from ~/.agents/skills/ in your home folder (older setups use ~/.codex/skills/, which still works). You can mention a skill explicitly with $skill-name, list them with /skills, and install curated ones with the built-in $skill-installer.
Cursor
Cursor reads project skills from .cursor/skills/ and your own from ~/.cursor/skills/. It also picks up skills in .agents/skills/, and for compatibility the Claude and Codex folders too, so one skill folder can serve all three tools. Type / in the Agent chat to find a skill by name.
The step-by-step setup for all three is in how to install skills.
A word on safety
A skill is a set of instructions your agent will follow, and some skills include scripts it will run. Treat one like any code you download: read it before you install it, prefer official sources (the tool's own marketplace, or the company that makes the framework), and be wary of a skill that asks the agent to send data somewhere or run commands that have nothing to do with its purpose.
FAQ
Do I need to know how to code to use skills?
No. Installing a skill is copying a folder or running one command, and writing one is writing clear instructions in Markdown. Knowing your tools helps you write better instructions, though.
Are skills the same as custom GPTs?
They're related ideas, but skills are files that live with your project and work across agents, while custom GPTs live inside ChatGPT. A skill can also include scripts and reference files that the agent uses on its own.
How many skills can I install?
Many. Because only names and descriptions are loaded up front, the cost per skill is small. The bigger risk is overlapping skills with similar descriptions, which can make the agent pick the wrong one.
Where can I find good skills?
Start with official sources: Anthropic's plugin marketplace, OpenAI's curated skills for Codex, and the skills published by the frameworks you use, like Remotion's. Community collections exist too, but read those carefully before installing.
Further reading
Written by Nil Martinez
Developer · DAM & DAW student
Developer studying multiplatform (DAM) and web (DAW) application development. I work every day with TypeScript, Angular, React, Java, Python, FastAPI, MySQL and Docker on Kubuntu, and I write about the tools I actually use.
Keep reading
How to Install Skills in Claude Code, Codex and Cursor
Where skill folders go in Claude Code, Codex and Cursor, how to install plugins and curated skills, the one command for every agent, and the Windows paths.
Skills & Plugins5 min read
How to Create Your Own AI Agent Skill (Step by Step)
Write a SKILL.md that Claude Code, Codex and Cursor actually use: when a skill is worth it, how to write the description, a full example and how to test it.
Skills & Plugins6 min read
Gemini Image Editing Prompts: Fix AI Images Fast
Copy-ready Gemini prompts to edit an image you already have: swap the background, remove objects, fix text, go vertical, and what to do when it gets stuck.
Prompt Library5 min read