There are two ways to create a Claude Skill: write the SKILL.md file yourself, or describe what you want and let a generator produce it. We'll cover the manual structure first so you understand what's happening, then the faster path.
What you need before you start
- A clear task you want Claude to handle consistently (e.g. reviewing code, writing release notes).
- Access to Claude with Skills enabled (Settings → Capabilities → Skills).
- A text editor - a skill is just plain text files.
Step by step: build a Claude Skill
- 1Create the skill folder. Make a folder named after your skill in kebab-case, e.g. code-reviewer/. The folder name should match the name in your frontmatter.
- 2Add a SKILL.md file. Inside the folder, create SKILL.md. This is the only required file. It starts with YAML frontmatter followed by markdown instructions.
- 3Write the frontmatter. Add a name (kebab-case) and a description. The description is the most important field - Claude reads it to decide when to use the skill, so state clearly what it does and when it applies.
- 4Write the instructions. In the markdown body, tell Claude how to perform the task: the process, the output format, and the rules. Explain why rules matter so Claude can generalize, and include examples of good output.
- 5Add reference files (optional). For longer skills, put supporting material (style guides, templates, scripts) in subfolders like references/ and point to them from SKILL.md.
- 6Install and test. Zip the folder, upload it in Claude under Settings → Capabilities → Skills, then try it in a chat to confirm it triggers and behaves as expected.
A minimal SKILL.md example
--- name: release-notes-writer description: Writes user-facing release notes from a list of merged changes. Use when the user provides a changelog, commit list, or PR titles and asks for release notes. --- # Release Notes Writer You turn a raw list of changes into clear, user-facing release notes. ## Process 1. Group changes into: New, Improved, Fixed. 2. Rewrite each item in plain language focused on the user benefit. 3. Drop internal-only changes (refactors, test updates) unless they affect users. ## Rules - Lead with the benefit, not the implementation. - Keep each item to one line. - If a change's impact is unclear, ask rather than guess.
Writing a description Claude will actually trigger on
The description field decides whether your skill ever loads. Claude reads every skill's name and description to pick which one applies to a request. Make it specific about both what the skill does and when to use it - include the words a user would naturally say.
Tip
Vague: "Helps with writing." Specific: "Writes user-facing release notes from a changelog or list of merged PRs. Use when the user asks for release notes." The second one triggers reliably.
The faster path: generate it
If you'd rather skip the boilerplate, describe the skill in plain English and generate a complete SKILL.md with MakeMySkill. It writes the frontmatter, instructions, and any reference files for you, which you can then download and refine. Browse the Claude Skill Library for ready-made examples you can copy and adapt.
Next steps
Once your skill is written, learn how to install it in Claude, and read the anatomy of a SKILL.md file to understand each part in depth.