How to Create a Claude Skill: A SKILL.md Walkthrough

To create a Claude skill, make a folder named after the skill, add a SKILL.md file with two frontmatter fields (name and description), and write the steps Claude should follow below them. Move long examples and rules into a references/ folder. Then zip the folder and upload it in Claude.ai, or copy it into your skills folder in Claude Code, and test it with real requests.

What goes inside a Claude skill folder?

One required file and a few optional ones. The folder name and the name field should match, and both use lowercase letters, numbers and hyphens.

weekly-threads-batch/
  SKILL.md
  references/
    formats.md
    examples.md
  templates/
    batch.md

SKILL.md holds the instructions. references/ holds anything Claude only needs some of the time: format rules, long example sets, a checklist. templates/ holds output shapes you want copied exactly. Claude reads the files inside a skill only when the instructions point to them, so a long reference file costs nothing until it is needed.

If you are new to the idea, our explainer on what Claude skills are covers how Claude decides when to load one and how skills differ from prompts and Projects.

How do you write the SKILL.md frontmatter?

The frontmatter is the short block between two lines of three hyphens at the top of the file. It has two fields, and Claude sees only these until a request matches.

---
name: weekly-threads-batch
description: Writes a week of Threads posts from the brand file, mixing one-liners, lists, questions and mini-stories across the brand's pillars. Use when the user asks for Threads posts, a Threads batch or a week of posts for Threads.
---

Field	Rules	What makes it good
`name`	Up to 64 characters; lowercase letters, numbers and hyphens; must not contain “claude” or “anthropic”	Names the job, such as `weekly-threads-batch`
`description`	Required, up to 1,024 characters	Says what the skill does and when to use it, with the phrases people actually type
Body (below the frontmatter)	Plain Markdown	Steps in order, the output format, a short checklist

The description does the triggering. Write it for the moment someone types a request. “Helps with social media” will rarely load. “Writes a week of Threads posts… Use when the user asks for Threads posts” will.

What should the body of SKILL.md say?

Write it like instructions for a capable new hire who has never seen your work. A structure that holds up:

Job. One paragraph on what a finished result looks like.
Inputs. What the skill needs from the user, and the one question to ask if something is missing.
Steps. Numbered, in the order you would do them yourself.
Output format. A template or a short example of the finished shape.
Checks. Five to eight lines to run before handing the result back.

Keep the body short. Anthropic’s guidance is to keep SKILL.md under about 500 lines and push detail into reference files. Link each one at the step that needs it: “Pick hooks from references/hooks.md.”

Context belongs in files too. A skill that writes posts is only as good as what it knows about the brand, so point it at a brand file instead of pasting voice rules into every skill. Our brand voice guidelines template shows what that file should hold, and content pillars for social media covers the topic list it reads from.

How do you install the skill you just made?

There are two places to put it, and the same folder works in both.

Where	How	Notes
Claude.ai (web and desktop)	Zip the folder, then upload it under Settings, Capabilities	Needs a paid plan with code execution turned on
Claude Code, personal	Copy the folder into `~/.claude/skills/`	Available in every project on your machine
Claude Code, one project	Copy the folder into `.claude/skills/` in the project	Shared with anyone who works in that repo

Zip the folder itself, so the archive contains weekly-threads-batch/SKILL.md, and not a loose SKILL.md at the top level. Our step-by-step guide on how to install Agent Skills in Claude covers checking that it loaded and fixing the usual upload errors.

How do you test a Claude skill before you rely on it?

Run it against requests you would really make, including the awkward ones. Five prompts are enough to find most problems:

The plain request. “Write this week’s Threads posts.” Does the skill load, and does the output follow your format?
A request in other words. “Give me 7 posts for Threads about budgeting.” If the skill doesn’t load, add those words to the description.
Missing input. Leave out the brand file. The skill should ask once, not invent a brand.
An edge case. Ask for twice the usual length or a format it doesn’t cover.
An unrelated request. Ask for a YouTube script. The Threads skill should stay out of it.

Change one thing at a time between runs, usually the description or one step, and run the same five prompts again. When a skill passes all five twice in a row, it is ready for daily use.

What mistakes stop a skill from working?

Most failures come from a handful of causes:

A vague description, so the skill never loads. Name the task and list trigger phrases.
Everything in one file, so the instructions bury the steps. Move examples and rules to references.
No output format, so every run looks different. Add a template.
Steps that assume knowledge, such as “use our usual hooks”. Put the hooks in a reference file.
One skill doing five jobs. Split it. A YouTube script template and a Threads post batch need different rules, so they work better as two skills.

FAQ

Do you need to code to create a Claude skill?

No. A skill can be nothing more than Markdown files. Skills may also include scripts that Claude runs, which is useful for things like counting characters, but most content skills are plain text instructions and examples.

Can Claude write a skill for you?

Yes. Describe the job, paste an example of the output you want, and ask Claude to draft the folder. Anthropic also publishes a skill-creator skill for this. Review the description and steps yourself before installing, since you know what the job really needs.

How many skills can you install at once?

Many. Claude reads only the name and description of each installed skill until a request matches, so a set of focused skills stays light. Overlapping descriptions cause more trouble than the count, so keep each skill’s job distinct.

Do Claude skills work in ChatGPT?

Not as skills. ChatGPT doesn’t load skill folders, but the text inside them is portable. Paste the instructions into a ChatGPT Project. Our comparison of Claude vs ChatGPT for content creation covers how each app stores reusable instructions.

Connect a finished system instead of building every method yourself. Nexin is a content system for running a brand, served as one connector in Claude and ChatGPT: Nexin Core interviews you and writes the brand file, and each channel module adds a tool whose jobs write for that platform and read it. You can still write your own skills next to it. Nexin drafts the content; you review and publish it. See pricing.