How to Create a Claude Skill: Step-by-Step Guide

Before You Create a Skill, Pick the Right Workflow

The best first skill is not the most impressive one. It is the workflow you already repeat. If you keep pasting the same review checklist, rewriting the same role prompt, or explaining the same output format, that instruction is a strong candidate for a Claude Skill.

This guide keeps the process practical: start with a narrow workflow, write the smallest useful file, test it against real work, and only add complexity when the skill proves it needs more structure.

A Claude Skill should package one repeatable job, not your entire operating system.

Claude Skill Scope: Personal vs Project

Decide where the skill should live before you write much text. Scope affects how broadly the skill applies and how much project-specific context you should include.

Step 1: Name the Skill by Outcome

Give the skill a short, outcome-based folder name. A good name is easy to type, easy to recognize, and narrow enough that you know what belongs inside it.

• Good: release-notes, support-reply-review, diff-risk-check, client-recap.
• Weak: writing, work-helper, claude-stuff, general-ai.

If the name needs "and" to explain it, split the idea. A skill that reviews code and writes customer emails is probably two skills.

Step 2: Create the Folder and SKILL.md File

A minimal Claude Skill is a folder containing SKILL.md. For a personal skill, create it under your Claude skills directory. For a project skill, create it inside the repo.

mkdir -p ~/.claude/skills/support-reply-review
touch ~/.claude/skills/support-reply-review/SKILL.md

For a project-scoped skill, the same structure usually sits inside the project:

mkdir -p .claude/skills/release-check
touch .claude/skills/release-check/SKILL.md

The folder is the package. The SKILL.md file is the entrypoint Claude reads to understand when and how to use that package.

Step 3: Write the Frontmatter First

Start with frontmatter because it forces you to define the skill clearly. The description should work like a precise trigger: what task, what input, what output, and when to use it.

---
name: support-reply-review
description: Review customer support replies for clarity, empathy, accuracy, escalation risk, and next-step quality before they are sent.
---

A vague description makes the skill hard to select. A specific description gives Claude a better signal and gives you a cleaner boundary for what belongs in the skill.

Step 4: Add the Instructions Claude Should Follow

After the frontmatter, write the operating instructions. Use short sections that match the way Claude needs to work: when to use the skill, what inputs matter, what process to follow, and what output shape to produce.

# Support Reply Review

Use this skill when the user asks for a review of a customer support reply,
escalation note, bug update, refund explanation, or resolution message.

Do not use this skill for legal, medical, security incident, or billing policy
decisions unless the user provides the approved policy text.

## Inputs

- Draft reply
- Customer issue or ticket summary
- Known policy, product limitation, or escalation rule if relevant

## Process

1. Identify the customer's core issue and emotional state.
2. Check whether the reply acknowledges the issue directly.
3. Flag unsupported promises, vague timelines, or risky claims.
4. Improve clarity and next steps without making the reply robotic.
5. Rewrite only if the user asks for a rewrite.

## Output

- Readiness: ready, needs edits, or risky
- Main concern: one sentence
- Suggested edits: concise bullets
- Optional rewrite: only when requested

This skill is narrow enough to trigger correctly and structured enough to produce repeatable reviews. It also includes a "do not use" rule, which is useful when the boundary could matter.

Step 5: Test It on Real Work

Do not judge a skill by whether the file looks tidy. Judge it by whether Claude behaves better on a real task. Run the skill on a normal example, then edit the file where the output drifted.

1. Use a realistic input: Test with an actual support reply, diff, draft, meeting note, or checklist.
2. Check skill selection: If Claude misses the skill, tighten the description.
3. Check output shape: If the answer ignores your format, make the output section more explicit.
4. Check false positives: If the skill runs on the wrong task, add negative conditions.
5. Check maintenance: If the file feels long, move examples or templates into supporting files.

A skill is finished when it improves normal work without needing extra explanation every time.

Step 6: Add Supporting Files Only When They Help

Many first skills should be one file. Add supporting files when the skill needs examples, templates, rubrics, or reference material that would make SKILL.md too long.

support-reply-review/
|-- SKILL.md
|-- examples/
|   |-- strong-reply.md
|   `-- risky-reply.md
`-- references/
    `-- escalation-checklist.md

Tell Claude when to open each file. Do not list reference files as decoration. For example: "Open references/escalation-checklist.md only when the draft mentions refunds, security, downtime, or customer data."

Common Mistakes When Creating Claude Skills

Most weak skills fail because they are too broad, too hidden, or too hard to maintain.

• Starting with a giant skill: Begin with one workflow and expand only when the test output proves it needs more.
• Writing a generic description: "Helps with writing" is not enough. Name the input, task, and output.
• Forgetting where the skill lives: Put personal habits in personal skills and project facts in project skills.
• Skipping negative conditions: Say when not to use the skill if the boundary is easy to confuse.
• Leaving the best copy on one machine: A useful skill becomes part of your work setup, so it needs a durable home.

Make the Skill Portable Once It Works

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude, so your setup follows you across every machine, repo, and tool.

This matters after the first few skills. The file that started as a local experiment can become a daily workflow, then a team standard. Without a shared library, the working version often ends up split across one repo, one laptop, one chat, and one teammate's notes.

Skill creation is only half the job. The other half is keeping the working skill available wherever the next task starts.

Claude Skill Creation Checklist

• Choose one repeated workflow with a clear output.
• Name the skill by outcome, not by category.
• Create a folder with a SKILL.md entrypoint.
• Write frontmatter with a concrete description.
• Add use conditions, inputs, process, and output format.
• Test on real work and refine based on the failure mode.
• Add supporting files only when they reduce clutter.
• Save the finished skill somewhere portable and versioned.

Related Resources

For the concept behind reusable skills, read what Claude Skills are. For file structure details, use the SKILL.md format guide. You can browse more guides from the resources hub, or start a first draft with the free Claude Skill Creator.

People Also Ask About Creating Claude Skills