- Guides
- Tool guides
- Claude skills and Agent Skills: write a procedure once, run it anywhere
Claude skills and Agent Skills: write a procedure once, run it anywhere
A skill is a folder of instructions your assistant loads only when a task needs it. Since the format became an open standard, the same folder works in Claude, ChatGPT, Gemini and Perplexity.
We have no affiliate deal with Anthropic, OpenAI, Google or Perplexity, and nobody paid to appear on this page.
What a skill is
A skill is a folder with one required file, SKILL.md, that tells an AI assistant how to do one job. The file opens with a short header, a name and a description, followed by plain instructions. The folder can also hold scripts, reference documents and templates 1.
The assistant does not read every skill in full. At startup it loads only each skill's name and description, about 100 tokens per skill. The full instructions load when a task matches, and extra files load only if a step needs them 1. That is why you can keep dozens installed without slowing every chat down.
Anthropic built the format and published it as an open standard in December 2025. On 22 October 2026 it donated Agent Skills, including the name, the GitHub organization and the agentskills.io domain, to the Agentic AI Foundation, the Linux Foundation group that also runs MCP. Engineers from Anthropic, Google, OpenAI and other companies now maintain it 2, and the project site says it is open to contributions from anyone 13.
Those numbers are Anthropic's own, from its October announcement 2. What matters for you: a procedure you write once is no longer tied to one vendor. If your team switches assistants, or a client uses a different one, the skill moves with you.
Skill or prompt? Make a skill when you have pasted the same instructions three or more times, or when the job has steps, a checklist or a template. A one-off question stays a prompt.
Which assistants read skills
The big four consumer assistants all accept a SKILL.md folder now, but where you upload it and who can use it differ. Anthropic names ChatGPT, Cursor, GitHub Copilot and VS Code among the platforms that support the standard 2; Google and Perplexity document their own upload paths.
| Assistant | Who gets it | How to add a skill |
|---|---|---|
| Claude apps | Free, Pro, Max, Ultra, Team and Enterprise, with code execution on 3 | Customize, Skills, +, Create skill, Upload a skill (ZIP) 5 |
| Claude Code | Same account; skills from claude.ai sync in 5 | Run /skills to see synced ones; see our Claude Code skills guide |
| ChatGPT | Workspace plans in beta; off by default until the owner enables them 6 | Ask "Build me a skill..." in a chat, then Install 6 |
| Codex | CLI, IDE extension, desktop app 8 | Put the folder in ~/.agents/skills or a repo's .agents/skills 7 |
| Gemini app | Age 18+, no paid plan needed 9 10 | Customize, Skills, Create, Upload a SKILL.md, folder or .zip 9 |
| Perplexity Computer | Anyone using Computer 12 | Plugins, Add custom, Upload plugin or skill 12 |
Claude
Claude reads skills across its apps, Claude Code and the API. On individual plans, turn on code execution and file creation under Settings, Capabilities first 3 4. Custom skills are private to the person who uploads them until they share them. On Team and Enterprise, you can share a skill with named colleagues, publish it to the whole organization, and owners can provision skills for everyone 5.
ChatGPT and Codex
OpenAI says its skills follow the Agent Skills open standard and can be exported to other tools that support it 6. In ChatGPT, a skill runs automatically when it fits, or you call it by typing @ and its name. Workspace owners decide who can create and share skills 6.
Plugins are how OpenAI distributes skills. Standalone skills work in the ChatGPT desktop app, Codex CLI and the IDE extension; skills bundled in a plugin also work in ChatGPT on the web and phone 8. Codex reads the same folder format and lets you call a skill with $ 7.
Gemini
Gemini skills replace Gems. On personal Google accounts, Gems turned read-only on 17 November 2026 and are removed on 17 December; Workspace business accounts follow in March 2027 10. Skills work on the Gemini web app, the mobile app and the Mac app, and you call one by typing / 9. Up to 100 can be active at once 10.
Google's help page does not name the open standard, but the upload takes the same thing: a SKILL.md file, or a folder or .zip with SKILL.md in its main folder. Uploads are capped at 100 MB in total, and scripts that need the internet do not run 9. For the move from Gems, see our Gemini Gems guide.
Perplexity and others
Perplexity builds every skill around a SKILL.md file "written in the open Agent Skills format" 11, and replaced its older Workflows with skills on 23 September 2026 12. A skill upload can be one .md file or a .zip of up to 100 files and 20 MB 12. Our Perplexity Computer guide covers the agent that runs them.
Write your first skill
Pick the prompt you retype most, give it a folder, and spend most of your effort on the description. The description is what the assistant reads to decide whether to load the skill, so it has to say what the skill does and when to use it 1.
The smallest valid skill is just the header. This is the minimal example from the specification 1:
---
name: skill-name
description: A description of what this skill does and when to use it.
---
Here is a complete, working one: a weekly client status email. Make a folder called weekly-client-update and save this inside it as SKILL.md:
---
name: weekly-client-update
description: Drafts the weekly status email to a client. Use when I ask for a client update, weekly recap, status email or progress note.
---
1. Ask which client this is for and what was delivered this week, if I have not said.
2. Open with the outcome for the client, not a list of tasks.
3. Keep it under 150 words, in plain sentences.
4. End with one next step and the date it will happen.
5. Never invent progress. If something is missing, ask.
The rules the header must follow 1:
name: 1 to 64 characters, lowercase letters, numbers and hyphens only, no hyphen at the start or end, no double hyphens, and it must match the folder name.description: up to 1,024 characters. Include the words you actually type when you ask for the task.- Optional fields:
license,compatibility,metadata(any key-value pairs, such as a version) andallowed-tools, which the spec marks experimental.
Tip: keep the description under 200 characters if you will use Claude. The specification allows 1,024, but Claude's upload form caps descriptions at 200 5.
- Zip the folderFor Claude, the ZIP must contain the skill folder at its root, and the folder name must match the skill name 5.
- Upload itUse the path for your assistant from the table above.
- Test it coldOpen a new chat and ask for the task in your own words, without naming the skill: "write this week's update for Acme".
- Fix the description, not the stepsIf the skill did not load, add the words you just typed to the description and test again.
You can also skip the typing. ChatGPT drafts a skill when you start a chat with "Build me a skill..." 6, Gemini has a Create with Gemini option 9, and Perplexity has Create with Computer 12. Read the draft before you install it.
Turn an SOP into a skill
A standard operating procedure maps neatly onto a skill folder: the trigger and steps go in SKILL.md, and the long material goes in reference files the assistant opens only when needed. The spec recommends keeping SKILL.md under 500 lines and moving detail into separate files 1.
Take a client onboarding SOP as the example. The folder looks like this, using the spec's optional references/ and assets/ folders 1:
client-onboarding/
├── SKILL.md
├── references/
│ ├── onboarding-sop.md
│ ├── done-checklist.md
│ └── example-welcome-email.md
└── assets/
└── kickoff-agenda.md
- Pick one SOP that runs weeklyOnboarding, a monthly report, a proposal review. Rare procedures don't repay the effort.
- Write the triggerThe description names the job and the phrases people use for it: "Use when someone asks to onboard a new client, set up a kickoff or send a welcome pack."
- Cut the SOP to numbered stepsPut only the steps in
SKILL.md. Point to the full document with a relative path, such as "see references/onboarding-sop.md for edge cases". The spec asks for references one level deep fromSKILL.md1. - Add one good exampleA finished welcome email you were happy with teaches tone faster than rules do.
- Define doneA short checklist file: what the output must contain before anyone sends it.
- Add a stop ruleTell the skill to say "I don't know" or ask, rather than invent a step the SOP does not cover.
- Version itPut a version and an owner in
metadata, so it is clear who signs off when the process changes 1.
Then test portability. Run the same skill on the same input in two assistants, say Claude and Gemini, and compare the outputs line by line. Where they differ, a step leans on one tool's habits; make it explicit. Expect differences around tools, since support for allowed-tools varies by platform 1, and Gemini will not run scripts that need the internet 9.
Developers can check the format with the reference validator named in the spec 1:
skills-ref validate ./my-skill
Read skills you didn't write: a skill can carry scripts, so open every file before you install one. Look for commands that download and run code, instructions to read whole key files, and anything that turns off permission prompts. Claude Enterprise can scan uploaded skills for malicious content 3, and security guidance for skill authors is still on the standard's roadmap, not shipped 2.
Skills vs projects, GPTs and Gems
Projects hold background; skills hold procedures. Gems and custom GPTs were a mix of both, and both are being folded into skills or plugins.
| Skill | Project (Claude, ChatGPT) | Gem or custom GPT | |
|---|---|---|---|
| What it holds | A procedure, plus optional scripts and files 1 | Background files, instructions and chats for one area of work | A persona with instructions and knowledge files |
| When it loads | Only when a task matches 1 | In every chat inside the project | When you open that Gem or GPT |
| Works across vendors | Yes, open standard 2 | No | No |
| Status | Active everywhere above | Active | Gems turned into skills from 17 Nov 2026 10; OpenAI documents moving GPTs to plugins 8 |
The two work best together. Keep one project per client for the documents and history, and use skills for the jobs you run across all clients, such as the weekly update or a proposal format. OpenAI draws the same line: skills are reusable workflows, projects are shared context 6.
If you built Gems or GPTs, now is the time to move them. Google converts personal Gems to skills automatically, with their supported files 10. For dates, sharing and file limits side by side, see Gems vs GPTs vs Projects; for Claude Projects, see How to use Claude.
Questions people ask
What are Agent Skills?
An open format for teaching AI agents a task: a folder with a SKILL.md file of instructions, plus optional scripts and reference files. Anthropic created it and in October 2026 handed it to the Agentic AI Foundation under the Linux Foundation.
What goes in a SKILL.md file?
A YAML header with a name and a description, then plain Markdown instructions. The name must match the folder name; the description says what the skill does and when to use it.
Do Claude skills work in ChatGPT and Gemini?
Mostly, yes. ChatGPT, Gemini and Perplexity all accept a SKILL.md folder. Check limits that differ by product, such as Claude's 200-character description on upload and Gemini's ban on scripts that use the internet, and test the skill in each one.
Are skills free to use?
In Claude, skills are on every plan including Free, with code execution on. Gemini skills need no paid plan. In ChatGPT, skills are a workspace feature that owners must turn on.
What is the difference between a skill and a plugin?
A skill is one procedure. A plugin is an installable package that can bundle several skills with connections to apps and other tools; OpenAI and Perplexity both distribute skills inside plugins.
Related
New features, explained the week they ship
195,000 readers get Uncover AI's practical AI briefing. We show you what is new and how to use it in your work.
Sources
- Agent Skills specification
- Anthropic: donating Agent Skills to the Agentic AI Foundation
- What are skills? (Claude Help Center)
- Using skills in Claude
- How to create custom skills (Claude)
- Skills (OpenAI Academy)
- Codex: build skills
- Codex: skills and plugins
- Create and manage skills for Gemini Apps
- About the transition from Gems to skills
- Perplexity: what is a skill?
- Perplexity: how to use Computer skills
- Agent Skills home