How to Create Your First Claude Skill — Step by Step

Creating a Claude Skill is simpler than you might think. A skill is fundamentally just a Markdown file that gives Claude specialized instructions for a specific task or domain. In this guide, you will go from zero to a working skill that you can use locally, share with your team, or submit to the public directory.

Step 1: Identify the Task

The best skills come from real, repeated workflows. Think about the instructions you find yourself giving Claude over and over. Maybe you always ask Claude to write tests in a specific way, or you have a particular documentation format, or there is a code review checklist you reference constantly. That repeated instruction set is your skill waiting to be created.

Good candidates for skills are tasks that require consistent, specific instructions, are performed frequently, benefit from domain-specific knowledge, and produce structured outputs. Avoid creating skills that are too broad or too narrow — a skill should be focused enough to be useful but general enough to apply across multiple conversations.

Step 2: Set Up the Folder Structure

Skills live in a specific folder structure. For personal skills that apply across all your projects, create a directory under ~/.claude/skills/. For project-specific skills, use .claude/skills/ in your project root. Each skill gets its own directory with a descriptive name.

For example, if you are creating a skill for React component testing, your structure would look like: ~/.claude/skills/react-testing/SKILL.md. The directory name should be lowercase, hyphenated, and descriptive. Inside this directory, the main file is always named SKILL.md.

Step 3: Write the SKILL.md File

Your SKILL.md file starts with YAML frontmatter that provides metadata about the skill. This includes a name, description, and optionally a list of trigger patterns that tell Claude when to activate the skill. After the frontmatter, write your instructions in clear, structured Markdown.

Write your instructions as if you are briefing a skilled colleague. Be specific about what you want: what format the output should take, what conventions to follow, what common mistakes to avoid, and what quality standards to meet. Use headers to organize different aspects of the instruction. Include examples when they would clarify your expectations. The more precise and well-organized your instructions, the better Claude will perform.

Step 4: Test Your Skill Locally

Once your SKILL.md is written, test it by starting a new Claude conversation in a context where the skill is accessible. Ask Claude to perform the task your skill is designed for and evaluate whether the output matches your expectations. Pay attention to edge cases — does the skill handle unusual inputs gracefully? Does Claude follow all your instructions consistently?

Iterate on the wording. If Claude misses a requirement, make the instruction more explicit. If it over-applies a guideline, add appropriate constraints. Good skills often go through several rounds of refinement. Test with different prompts and scenarios to make sure the skill is robust.

Step 5: Share and Submit

Once your skill is working well, you have several sharing options. For team use, commit it to your project repository in the .claude/skills/ directory so colleagues automatically pick it up. For wider distribution, publish it as a GitHub repository and submit it to our directory. When submitting, provide a clear title, description, and appropriate category tags so others can find your skill easily.

Tips for Writing Effective Skills

Keep instructions actionable and specific rather than vague and abstract. Structure your content with clear headers so Claude can quickly locate relevant sections. Include a brief overview at the top explaining the skill's purpose. Use bullet lists for checklists and requirements. Avoid unnecessary verbosity — concise instructions tend to produce more consistent results than lengthy ones. Finally, always include information about what the skill should not do, as guardrails are just as important as instructions.