A custom Claude Skill lets you save a workflow once and have Claude reuse it automatically, instead of retyping the same instructions in every new conversation. Skills follow an open standard, so a skill you build for Claude also works in other AI tools that support the same format.
What You Need Before You Start
A custom skill only needs one required file, so there is very little setup involved.
At minimum you need a folder containing a single file named SKILL.md. That file must start with a short YAML header holding a name and a description, followed by plain-language instructions below it. Everything else, including scripts, templates, or reference documents, is optional and only needed if your workflow calls for it.
How to Write the SKILL.md File
This file is the entire skill, so getting the header right matters more than anything else in it.
Give the skill a short, lowercase name using hyphens instead of spaces, such as weekly-report or contract-review, keeping it under 64 characters. The description is the part that decides whether Claude ever uses the skill, since Claude reads only the name and description at first and pulls in the full instructions later, when your request matches what the description says. Write it as a plain sentence stating exactly what the skill does and when to use it, keeping it under 200 characters. Below the header, write the instructions the way you would explain the task to a new hire on their first day, in plain steps, with no special syntax required.
---
name: weekly-report
description: Drafts my weekly project status report from raw notes.
Use when I provide bullet-point updates and ask for the report.
---
Write the report in three sections: Progress This Week,
Blockers, and Next Steps...If you want a skill to run only when you ask for it by name, rather than whenever Claude thinks it applies, add disable-model-invocation: true to the header. This is a common choice for skills tied to actions with real consequences, such as deploying code or sending a message, where you want to control the timing yourself.
How to Create a Skill by Having Claude Draft It
You do not have to write SKILL.md by hand, since Claude can draft it for you two different ways.
If you have already worked through a task with Claude in a normal conversation and liked how it turned out, tell Claude directly in that chat to turn what you just did into a skill. Claude will draft the name, description, and instructions based on what already happened, and you just review the draft before saving it. If you have not run the workflow yet but know what you want, start a new chat and ask Claude to help you create a skill for the task. Claude will ask what the skill should do, what input it should expect, and how you want the output structured, then assemble the instructions from your answers.
How to Add Supporting Files to a Skill
Some workflows need more than written instructions, and a skill folder can carry that too.
Add a scripts/ folder for code Claude can run, a references/ folder for checklists or documentation the task should follow, or an assets/ folder for templates and examples. Claude only opens these files when the task actually calls for them, so a skill with several supporting files does not slow anything down until it is triggered.
weekly-report/
├── SKILL.md # Required
├── scripts/ # Optional
├── references/ # Optional
└── assets/ # OptionalHow to Save Your Custom Skill on Claude.ai
Once your SKILL.md file is ready, saving it as a usable skill takes a few clicks.
Go to Settings > Skills, click Add, and choose Write skill instructions if you are typing it directly, or Upload a skill if you already have it saved as a .zip file. If you used the conversation method above, follow the prompts Claude gives you to save it straight from the chat instead. If you are packaging the zip yourself, make sure the folder name matches the skill’s name field and that the folder sits at the root of the zip rather than nested inside another subfolder, since this is the most common reason an upload fails. For the full walkthrough of the Skills panel, including the free-plan access details and the Browse option for ready-made skills, see our guide on how to install Claude Skills.
How to Save Your Custom Skill in Claude Code
In Claude Code, there is no upload step at all, since skills are just folders sitting in the right place.
Place your finished skill folder inside ~/.claude/skills/ if you want it available in every project, or inside .claude/skills/ in a specific project’s root directory if you want it shared with your team through version control. Claude Code discovers the folder automatically. If you create a brand new top-level skills directory that did not exist when the session started, restart Claude Code so it picks up the new folder.
The folder’s name also becomes the command you type to run the skill directly. A skill saved at .claude/skills/weekly-report/SKILL.md can be invoked any time by typing /weekly-report, regardless of whether Claude would have triggered it automatically.
How to Test That a Skill Actually Works
A skill is only useful if it triggers at the right moment, so testing it before relying on it is worth the extra step.
Start a new conversation and give Claude a request that matches the exact situation described in the skill’s description. If Claude uses the skill automatically, it worked. If it does not, the most common cause is a description that is too vague, so rewrite it to state clearly what the skill does and when it applies. You can also skip the guesswork entirely and ask Claude directly to use the skill by name while you confirm the output matches what you intended.
Frequently Asked Questions
Do I need to know how to code to create a Claude Skill?
No. A skill is a plain-text file written in natural language. Supporting scripts are optional and only needed for workflows that require running code.
What should I name my skill?
Use a short, lowercase name with hyphens instead of spaces, such as investor-update or lease-abstract. The name is just a label, so the description is what actually determines when Claude uses it.
Can I edit a skill after I create it?
Yes. On claude.ai, open the skill in the Skills panel and edit it directly if in-place editing is available, or download it, revise it in a new conversation, and re-upload the updated version. In Claude Code, editing the SKILL.md file in its folder takes effect in your current session immediately.
Why is my skill not triggering when I expect it to?
The description is almost always the cause. Claude matches your request against that description, so a vague one like “helps with reports” will not fire reliably. Rewrite it to state specifically what the skill does and when to use it.
Is there a length limit for the name and description?
Yes. The name is capped at 64 characters and the description at 200 characters on claude.ai. Keep the description specific but short, since that is what Claude matches your requests against.
Can I turn a skill I built for one platform into one that works elsewhere?
Yes. A SKILL.md file created for claude.ai works the same way in Claude Code, since both read the same file format. The API requires uploading the file through the Skills API first before it can be referenced by a skill_id.
