What Are Claude Skills? The Complete Guide

Claude Skills, Defined Simply

A Claude Skill is a reusable capability package for Claude. Instead of explaining a process from scratch in every conversation, you write the process once and save it as a skill. Claude can then load that skill when the task matches, or you can invoke it directly in Claude Code with a slash command such as /summarize-changes.

Think of a skill as a small operating manual for a specific job. It might tell Claude how to review a pull request, convert meeting notes into a client-ready recap, follow your company's writing style, generate a deck outline, or run a repeatable QA checklist. The key difference from a normal prompt is that the instruction lives as a reusable artifact, not as text you keep hunting for and pasting again.

A skill turns repeated instruction into reusable infrastructure.

What Is Inside a Claude Skill?

Every Claude Code skill starts with a folder and a SKILL.md file. The SKILL.md file is the entrypoint: it describes when Claude should use the skill and what Claude should do after the skill loads. More advanced skills can include extra files so the main instructions stay focused.

The description is more important than most people expect. Claude uses it to decide whether the skill is relevant. A vague description like "helps with writing" makes the skill hard to select. A specific description like "turns raw customer call notes into a concise QBR recap with risks, wins, and next steps" gives Claude a much better trigger.

A Simple Claude Skill Example

Here is a minimal Claude Code skill for summarizing a work-in-progress Git diff. It is intentionally narrow: it does one job, it says when to use it, and it gives Claude a clear output shape.

---
description: Summarize uncommitted Git changes and flag risky edits. Use when the user asks what changed, wants a commit summary, or asks for a quick diff review.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes in three bullets.
Then list any risks, missing tests, hardcoded values, or follow-up checks.
If there are no changes, say there are no uncommitted changes.

This is more durable than a pasted prompt because it can live in your skills folder, stay attached to the workflow, and be reused across sessions. It is also easier to improve. If the review misses test risks, you edit the skill once instead of rewriting the same reminder in every chat.

Where Claude Skills Live in Claude Code

Claude Code supports skills at different scopes. The scope decides who can use the skill and where it appears. This matters because not every skill belongs everywhere.

• Personal skills: Put them in ~/.claude/skills/[skill-name]/SKILL.md when you want the skill available across your projects.
• Project skills: Put them in .claude/skills/[skill-name]/SKILL.md when the skill only makes sense for one repo.
• Nested project skills: In monorepos, package-specific skills can live in nested .claude/skills folders so they apply near the code they describe.
• Plugin skills: Plugin-provided skills can bundle instructions with other plugin assets and use namespaced commands.

Use personal skills for your repeatable operating style: code review habits, writing preferences, planning templates, research workflows, or release checklists. Use project skills for repo-specific facts: architecture rules, deployment steps, test commands, migration conventions, or domain language that should not leak into unrelated work.

Claude Skills vs Prompts vs Custom Instructions

The fastest way to understand Claude Skills is to compare them with the tools people already use. Prompts, custom instructions, and skills all shape AI behavior, but they solve different problems.

A good rule: if you only need it once, write a prompt. If you need it every day, make it a skill.

When Should You Create a Claude Skill?

Create a Claude Skill when the same instruction has become a workflow. The signal is not length; the signal is repetition. If you keep pasting the same checklist, asking Claude to follow the same rubric, or reattaching the same reference material, the workflow is ready to become a skill.

• You repeat the same prompt often: Code review, weekly planning, changelog writing, customer recap drafting, or incident review.
• The task has rules: Tone, output format, compliance constraints, naming conventions, or quality gates.
• The task benefits from examples: Great skills often include a strong example output so Claude can match the expected shape.
• The task needs supporting files: Brand voice, templates, product facts, or validation scripts can live with the skill.
• The workflow should travel: If losing the prompt would slow you down on a new laptop or repo, it belongs in a managed skill library.

Do not create a skill for every clever prompt. Too many overlapping skills create selection noise. Prefer fewer, clearer skills with strong descriptions and obvious names.

The Portability Problem Claude Skills Expose

Claude Skills solve the repeatability problem, but they also reveal a new operational problem: where do your best skills actually live? One useful skill might sit in a repo, another in a personal folder, another on an old laptop, and another in a teammate's notes. When you switch machines or start a new project, the setup you carefully built often disappears.

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 most for people who work across several agents. A Claude Skill is useful inside Claude, but the underlying workflow may also belong in Codex, ChatGPT, Claude, or any agent connected over MCP. The durable asset is not the chat where you first wrote the instruction. The durable asset is the skill itself.

Common Claude Skill Mistakes

Most weak skills fail because they are either too vague or too large. A skill should be easy for Claude to select and cheap to load into context.

• Writing a description that is too broad: "Helps with docs" is weak. "Turns rough release notes into customer-facing changelog entries" is strong.
• Stuffing everything into SKILL.md: Put detailed examples, templates, or long references in supporting files and point Claude to them.
• Mixing unrelated jobs: A skill that reviews code, writes docs, plans releases, and drafts emails should probably be four skills.
• Forgetting invocation style: Decide whether Claude should load the skill automatically or whether it should only run when you call it directly.
• Never versioning the skill: The first draft is rarely the best draft. Treat skills like living workflow assets.

The best Claude Skills are narrow enough to be selected correctly and detailed enough to remove repeated explanation.

How to Start With Claude Skills

Start by turning one painful repeated workflow into a skill. Do not begin with a giant library. Pick the instruction you paste most often, then make it explicit.

1. Choose one repeated task: Examples: review a diff, write a client recap, produce a research brief, or generate a migration checklist.
2. Name the skill by outcome: Use names like client-recap, release-notes, or security-review.
3. Write the description first: Say what the skill does and when Claude should use it.
4. Add the steps Claude must follow: Use numbered instructions, output rules, and quality checks.
5. Test it on real work: Run the skill on a normal task, then edit the instructions where the output drifted.
6. Save and sync the winner: Once the skill works, keep it somewhere durable instead of leaving it trapped in one repo.

If you want a faster first draft, use the free Claude Skill Creator. It helps turn a rough role, task, and output goal into structured skill instructions you can refine.

People Also Ask About Claude Skills

What are Claude Skills?

Claude Skills are reusable folders of instructions, reference files, and optional scripts that teach Claude how to perform a specific task consistently. A skill usually starts with a SKILL.md file and can be invoked automatically when relevant or directly by name in Claude Code.

Are Claude Skills the same as prompts?

No. A prompt is usually a one-time instruction pasted into a chat. A Claude Skill is a reusable package that can include instructions, examples, templates, and supporting files, so the same workflow can be used again without rewriting it.

Where do Claude Code skills live?

Personal Claude Code skills live under ~/.claude/skills/[skill-name]/SKILL.md and apply across projects. Project skills live under .claude/skills/[skill-name]/SKILL.md and apply to that project. Claude Code can also discover nested project skills in monorepos.

Can Claude Skills include more than one file?

Yes. A skill needs a SKILL.md entrypoint, but it can also include templates, examples, scripts, checklists, brand guides, or other reference files. Multi-file skills are useful when the main instructions should stay short while detailed materials live nearby.

How do I keep Claude Skills synced across computers?

The simple manual approach is to keep skills in a versioned folder and copy or symlink them into Claude Code. Prompttly gives you a managed library that syncs skills into Claude Code and Codex as real skill folders, with version history across surfaces.

Related Resources

For more context, start from the resources hub. If you are still shaping a reusable workflow, read From Raw Idea to Pro Prompt and The Periodic Table of Prompt Engineering. If your main concern is production consistency, the SaaS prompting guide shows how repeatable instructions become operational assets.