Claude skills: what they are and how to write good ones

What a Claude skill is

A skill is a folder with one file at its heart, SKILL.md: a name, a description and instructions in plain language. The folder can also hold templates, examples or scripts that the instructions point to.

Claude does not read every skill all the time. It reads the name and description of each one, and loads the full instructions only when a task matches. That is why you can have dozens of skills without slowing anything down, and why the description matters more than anything else in the file.

Skills work on every Claude plan, Free included, as long as code execution is turned on: on the web, desktop and mobile, in Claude Code and through the API. The format is an open standard, Agent Skills, so the same file also works in ChatGPT, GitHub Copilot and Cursor.

One skill, one task

The most common mistake is a skill that tries to cover a whole department. "Marketing" is not a skill. "Write the monthly campaign report" is.

A narrow skill is easier for Claude to match to the right moment, easier for you to test and easier to reuse: the same brand voice check can sit in the newsletter job, the campaign job and the website job.

How to write a good skill

Anthropic publishes guidance on writing skills. Translated into how a team actually works, it comes down to seven things.

+

The description says what and when

Claude decides from the description alone whether to load the skill. Say what it does and the moments people ask for it, in the third person and in under 200 characters, which is the limit when you upload a skill to Claude: "Writes the monthly marketing report. Use when someone asks for the monthly report or how marketing did last month."

+

Steps in order

Numbered steps, in the order your best person does them. Not a philosophy, a recipe.

+

A fixed result

Say exactly what comes out: sections, length, format. The same task should give the same shape every time.

+

One real example

Show one finished example at the level you expect. It does more than a page of adjectives.

+

Rules for the gaps

Tell it what to do when information is missing. "Write unknown and what to check" beats a confident guess.

+

Short, with details in separate files

Keep SKILL.md tight; Anthropic suggests under 500 lines. Long references and templates go in their own files that the skill points to.

+

Tested on real work before it is shared

Run it on three real tasks, compare with what your best person would have done, fix it, repeat. Test it in the models and assistants your team actually uses, since a skill that works in one can miss in another. Then roll it out.

The mistakes we see most

Most weak skills fail in the same five ways. The sixth mistake is about safety.

+

Explaining what Claude already knows

Claude knows what a press release is. Write down what is specific to you: your template, your rules, your tone.

+

A vague description

"Helps with documents" will never be picked. Name the task and the words people use when they ask for it.

+

No example

Without one, every result is a new interpretation.

+

Things that change, written into the instructions

Dates, prices and names go out of date. Put them in a separate file, or the skill quietly starts giving old answers.

+

Nobody owns it

A skill is a process document. Give each one an owner who updates it when the process changes.

+

Installing skills from strangers

A skill can carry scripts and reach the data you give Claude. When Snyk scanned almost 4,000 public skills in February 2026, 76 were built to do harm. Use skills from sources you trust and read every file before you install one.

Skills, projects, connectors and plugins

Four things people mix up. They do different jobs, and good setups use all four.

Skills vs MCP in one line: the skill knows how, the connector gives access. A skill that writes the weekly pipeline review needs a CRM connector to read the deals. See all our MCP connectors.

Skills and plugins in Claude Cowork, now part of every chat

Cowork was the part of Claude that does the work instead of explaining it: it works through your files, connected tools and the web and comes back with a finished result. Since September 2026 it is no longer a separate mode. Chat and Cowork are one Claude, and Claude decides itself whether to answer or to do the job. Skills are what make that result yours, in every conversation.

Plugins bundle skills, connectors and commands, so a whole team can install the same setup at once. With scheduled tasks, a job runs on its own every day, week or month, even with the laptop closed. That is where a set of skills becomes an agent: read our guide to AI agents.

Skills in ChatGPT and other assistants

Agent Skills became an open standard in December 2025, and the big tools have adopted it: GitHub Copilot, Cursor and OpenAI. ChatGPT has had skills since July 2026 on Business, Enterprise, Healthcare and Edu, and Codex reads the same SKILL.md files.

Custom GPTs retire on 11 December 2026. OpenAI moves them into plugins, and each GPT’s instructions become a skill. A company that built GPTs ends up with skills either way.

The practical lesson: write skills in plain Markdown, with nothing tied to one vendor, and they travel. That matters the day half the company prefers ChatGPT.

Skills for a whole company

One person with ten skills is a productivity tip. Fifty people with five hundred private skills is a mess: three versions of the proposal template, nobody knows which one is right, and the best one leaves with the person who wrote it.

Treat skills like process documents: one library, an owner per skill, a version history, and a way to see which ones are used. On Claude Team and Enterprise, owners can provision skills for the whole organisation, and a plugin can be made available, installed by default or required. Deployed OS does it across assistants: one library of company skills that reaches Claude, ChatGPT and Copilot, updated centrally the same day, with usage per skill so you can see what works.