AI agents got good at reasoning fast. What they still lack, out of the box, is your way of doing things: your architecture rules, your brand voice, your release checklist, the five steps your team always follows to set up a new client.
You can paste those instructions into every conversation, or you can package them once as an agent skill. In this guide we explain what agent skills are, how Claude skills and Codex skills work, how to write a SKILL.md, how skills relate to MCP and what we have learned using them in our own teams.
Last reviewed: November 2026.
What are agent skills?
Agent skills are reusable packages of instructions, and optionally scripts and templates, that teach an AI agent how to do a specific task. Each skill lives in a folder with a SKILL.md file at its center.
Anthropic introduced skills for Claude in October 2025 and later published the format as an open standard. Since then, other agents have adopted it: OpenAI Codex, GitHub Copilot, Cursor and Microsoft’s agent tools can all read the same SKILL.md files. That is why you will see the same idea called “Claude skills”, “Codex skills” or just “agent skills”.
A useful way to think about it: if the model is a smart new hire, a skill is the onboarding guide for one part of the job. It doesn’t make the hire smarter. It makes them do the job the way your team expects.
How agent skills work
The trick that makes skills practical is that the agent doesn’t read them all the time.
- At the start, the agent only sees each skill’s name and short description. That costs very little context, so an agent can have dozens of skills installed.
- When a task matches a description (“write a release note”, “review this pull request”), the agent loads the full instructions of that skill.
- If the skill points to extra files, like a template, a reference document or a script, the agent opens them only when it needs them.
This step-by-step loading means skills can be long and detailed without slowing down every conversation. It also means the description matters a lot: if it’s vague, the agent won’t know when to use the skill.
What a SKILL.md looks like
A skill can be as small as one file. Here is a simplified example for writing release notes:
---
name: release-notes
description: Writes customer-facing release notes from a list of merged pull requests. Use when the user asks for release notes or a changelog.
---
# Release notes
1. Group the changes into New, Improved and Fixed.
2. Write for customers, not developers: no ticket numbers or internal names.
3. One sentence per change, starting with a verb.
4. Leave out internal refactors unless they change performance.
5. End with a link to the full changelog.
The header has two required fields: name and description. The body is plain Markdown. Next to it, the folder can hold examples of good release notes, a template or a script that pulls the list of merged pull requests.
Agent skills vs MCP
Skills and MCP are often mentioned together, and they solve different problems.
| Agent skills | MCP | |
|---|---|---|
| What it gives the agent | Know-how: steps, rules, checks | Access: tools and data in other systems |
| What it is made of | Markdown instructions, plus optional files and scripts | A server that exposes tools through a protocol |
| Who usually writes it | The team that owns the process | Engineers who own the system |
| Example | ”How we review a pull request" | "Read and comment on pull requests in GitHub” |
MCP gives the agent hands. Skills tell it what to do with them. A good setup uses both: an MCP server lets the agent read your tickets and your repository, and a skill tells it how your team triages bugs, which labels to use and when to ask a person.
If you want to go deeper on the access side, our guide on what an MCP server is covers how MCP works and how to secure it.
Agent skills examples
Skills are useful anywhere a task has a “right way” that lives in people’s heads. Some examples:
- Engineering: code review checklists, how to write tests in your codebase, how to add a new API endpoint following your architecture, how to prepare a release.
- Documents: proposals, reports and decks that follow your brand, with your templates and fonts.
- Operations: onboarding a new client, preparing a weekly report from several sources, triaging support tickets.
- Data: running the same analysis every month with the same definitions, so numbers are comparable.
At HitOcean we use skills in our own day-to-day work. Our process for planning and building SEO landing pages is a skill: it walks an agent through keyword research, checks for pages competing for the same search, writes the brief and builds the page with our existing components. Our branded documents and presentations come from skills too. The benefit is consistency: the agent follows the same steps every time, and when we improve the process, we update one file.
How to write a good agent skill
What we have learned writing and maintaining skills:
- One skill, one job. “Write release notes” works. “Help with everything about releases” doesn’t trigger reliably.
- Write the description for the agent, not for people. Say what the skill does and when to use it, with the words a user would actually type.
- Steps over prose. Numbered steps and checklists are followed more reliably than paragraphs of advice.
- Show, don’t just tell. Add one or two examples of good output in the folder.
- Put the checks in the skill. “Before finishing, verify that…” catches more mistakes than hoping the agent remembers.
- Keep it in version control. Skills are part of how your team works. Review changes to them like code.
Security: treat skills like code
A skill can include scripts that the agent runs, and instructions that change what the agent does. That makes a skill from an unknown source similar to installing an unknown package:
- Read third-party skills before installing them, including any scripts.
- Limit what skills can run. Most agents let you decide which commands need approval.
- Don’t put secrets in skills. API keys and passwords belong in your secret manager, not in a Markdown file.
- Combine with permissions. A skill can tell an agent what to do, but the agent’s permissions decide what it can actually do. Keep those tight.
Should your team use agent skills?
If your team already works with AI agents, skills are one of the cheapest ways to make them more reliable. Start with the task you explain to the agent most often, write it down as a skill and see whether the results get more consistent.
For engineering teams, skills pair naturally with the tools in our guide to the best AI coding agents. For company processes that need an agent connected to your own systems, that is the work we do in our AI agents for business service: the agent, the integrations and the skills that make it follow your rules.
Frequently asked questions
What are agent skills in simple terms?
Agent skills are folders of instructions, and optionally scripts or templates, that teach an AI agent how to do a specific task your way. The agent reads a skill only when the task calls for it, so it can have many skills without overloading its context.
What is a SKILL.md file?
It is the main file of a skill. It starts with a short header that gives the skill a name and a description of when to use it, followed by the instructions in plain Markdown. The agent uses the description to decide when to load the rest.
What is the difference between agent skills and MCP?
MCP gives an agent access to tools and data in other systems. Skills teach the agent how to do a job: the steps, the rules and the quality checks. They work well together: a skill can tell the agent which MCP tools to use and in what order.
Which AI tools support agent skills?
Anthropic introduced skills for Claude in October 2025 and published the format as an open standard a few months later. By 2026, OpenAI Codex, GitHub Copilot, Cursor and Microsoft's agent tools also read SKILL.md files, so one skill can work across several agents.