How to Create a Claude Skill (Step-by-Step Guide)

Anyone can create a Claude Skill. It’s a plain text file — no code, no deployment, no configuration. If you can write a clear set of instructions, you can build a skill that makes your AI agent dramatically more consistent at any repeated task.

This guide covers everything: what goes in a skill file, how to structure it well, how to test it, and how to share it with others.

What you’re actually building

A Claude Skill is a file named SKILL.md stored in a folder inside your agent’s skills directory. That’s it. When Claude Code starts a session, it reads every installed skill and uses those instructions when the relevant work comes up.

The structure is:

~/.claude/skills/
  your-skill-name/
    SKILL.md

The SKILL.md file is written in Markdown. Claude reads it as standing instructions — not a one-off prompt, but a permanent process definition for a specific type of task.

The anatomy of a well-written skill

A good skill has four components. All four matter. Skills that skip any of them produce inconsistent output.

1. Name and description

Tell Claude what this skill is and when it applies. Be specific — vague names lead to vague activation.

# Cold Email Writer

Use this skill when asked to write cold outreach emails,
prospecting emails, or B2B sales sequences.

2. Trigger conditions

Define exactly what activates this skill. This prevents the skill from firing when it shouldn’t, and ensures it fires when it should.

## When to use this skill

Activate when the user asks to:
- Write a cold email or outreach sequence
- Draft follow-up emails after no response
- Improve or rewrite an existing cold email
- Create a multi-touch email campaign

3. Required inputs

Before starting the task, gather what you need. A skill that starts without the right context produces mediocre output.

## Before starting, confirm you have:

1. **Target audience** — who is this email going to? Role, company size, industry.
2. **Your offer** — what are you asking for? Demo, call, intro?
3. **Key pain point or hook** — why should they care?
4. **Sender context** — who is sending this? Company name, what you do.
5. **Tone** — formal, conversational, direct?

If any of these are missing, ask before writing.

4. Step-by-step process

This is the core of the skill. Don’t write vague instructions — write a specific process the agent executes every time.

## Process

1. **Research the opening line**
   - Write a personalised first sentence specific to this recipient
   - Reference their company, role, a recent event, or a specific problem
   - Never start with "I" or "My name is"

2. **State the value proposition in one sentence**
   - Focus on outcome, not features
   - Be specific: "reduce contract review time by 60%" not "improve legal workflows"

3. **Call to action**
   - Ask for one thing only
   - Make it low-commitment: "worth a 15-minute call?" not "book a demo"

4. **Write subject line last**
   - 4–7 words
   - Avoid spam triggers: free, guaranteed, no obligation
   - Match the tone of the body

5. **Write 2 follow-up variants**
   - Follow-up 1 (3 days): brief, adds a new angle
   - Follow-up 2 (7 days): short, asks if timing is wrong

## Output format

Deliver as three separate blocks:
- Subject line
- Email body (under 150 words)
- Follow-up 1
- Follow-up 2

A minimal working example

Here’s a complete, functional skill for code review — stripped to the essentials:

# Code Reviewer

Use this skill when asked to review code, check a PR, or give feedback on implementation.

## Trigger

Activate on: "review this", "check this code", "feedback on my PR", "what do you think of this implementation"

## Required inputs

- The code to review (file, snippet, or PR diff)
- Language and framework (if not obvious)
- Context: is this new code, a refactor, or a bug fix?

## Review process

Check in this order:

1. **Correctness** — does it do what it's supposed to do? Edge cases?
2. **Security** — injection risks, auth issues, exposed secrets, input validation
3. **Performance** — N+1 queries, unnecessary loops, blocking operations
4. **Readability** — naming, function length, comments where needed
5. **Tests** — are critical paths covered? Is the test meaningful?

## Output format

Structure your response as:

**Summary** (2–3 sentences overall assessment)

**Issues** (numbered list, severity: critical / major / minor)

**Suggestions** (improvements that aren't blockers)

**What's good** (at least one thing — genuine, not filler)

How to install your skill

Once you’ve written your SKILL.md, put it in the right place:

Claude Code:

mkdir -p ~/.claude/skills/your-skill-name
# save your SKILL.md file to that folder

The skill is active immediately in your next Claude Code session. No restart required.

Test it by opening a new Claude Code session and asking it to do the task your skill covers. Check:

Does it ask for the right inputs before starting?
Does it follow your process?
Is the output in the format you defined?

If not, iterate on the skill file and try again.

Common mistakes

Too broad a trigger. A skill named “Developer Assistant” that activates on almost everything will conflict with other skills and produce generic output. Narrow it down — “PR Code Reviewer”, “API Design Critic”, “Database Schema Reviewer”.

Skipping the inputs section. Skills that don’t specify required context will start working with incomplete information. Define what you need upfront and tell the skill to ask if it’s missing.

Vague process steps. “Write good code” is not a process step. “Check for N+1 queries in any ORM calls” is. The more specific your steps, the more consistent the output.

Too long. A 3,000-word skill degrades performance — the model holds all of it in context even when 80% isn’t relevant to the current task. Aim for under 500 words for the process section. If it’s longer, split it into multiple focused skills.

Duplicating custom instructions. If “always use British English” is in your custom instructions, don’t repeat it in every skill. Custom instructions are for preferences; skills are for processes.

Making your skill shareable

If you want others to install your skill with the standard npx skills add command, publish it to GitHub:

Create a public repository
Create a folder: skills/your-skill-name/
Add your SKILL.md to that folder
Push to GitHub

Others can then install it with:

npx skills add your-github-username/your-repo --skill skills/your-skill-name

If you want your skill listed on findskills.co, submit it here — we review every submission and add editorial descriptions before listing.

Reference files

Some skills include additional reference files the agent uses alongside the main instructions — templates, checklists, example outputs, or lookup tables.

To add reference files:

~/.claude/skills/your-skill-name/
  SKILL.md
  references/
    output-template.md
    checklist.md

Reference your files in the SKILL.md:

## Reference files

- `references/output-template.md` — use this structure for the final deliverable
- `references/checklist.md` — run through this before marking the task complete

Claude Code reads these files when the skill is active and uses them as context alongside the main instructions.

What makes a great skill

The best skills on findskills.co share a few qualities:

Narrow scope. They handle one type of work extremely well rather than trying to cover many things broadly.
Specific inputs. They know exactly what information they need before starting.
Opinionated process. They don’t leave the agent to figure out how — they define a clear sequence.
Defined output. The reader knows what they’ll get before they read it.

If your skill passes those four tests, it’ll produce consistently good output every time someone installs it.

Browse existing skills for inspiration

The fastest way to learn good skill structure is to read skills that are already working well. Every skill on findskills.co has its full SKILL.md content readable in the browser — no install required.

Start with a few well-structured examples:

RAG Architect — shows how to structure a complex technical skill
Cold Email Writer — shows clear trigger conditions and multi-step output
Legal Review Contract — shows how to handle domain-specific workflows

→ Browse all skills · Submit your skill · Install guide