If you've spent any time with Claude Code, you already know it's a powerful AI coding assistant. But knowing how to create Claude Code skills is what separates developers who use it occasionally from those who get 10x more done with it every day. Skills let you encode your own workflows, conventions, and repeatable tasks into reusable commands — and in this guide, you'll learn exactly how to build them.
What Are Claude Code Skills?
Claude Code skills (sometimes called slash commands or custom commands) are Markdown files that tell Claude Code how to behave when you invoke a specific command. Think of them as saved, parameterized prompts that live alongside your project or in your global config. When you type /write-tests or /review-pr, Claude Code reads the corresponding skill file and follows its instructions precisely.
Unlike a throwaway prompt you type in the chat, a skill is:
- Persistent — it lives in a file and can be version-controlled.
- Reproducible — every teammate gets the same behavior.
- Composable — you can build a library of focused skills and chain them.
Skills are stored as .md files inside a .claude/commands/ directory — either at the project level (.claude/commands/ in your repo root) or globally (~/.claude/commands/ for use across all projects).
How to Create Claude Code Skills: The File Format
Every skill file follows a simple structure: a YAML frontmatter block followed by the instruction body. Here is a complete, real-world example of a skill that automates writing unit tests:
---
name: write-tests
description: Generate unit tests for the selected file or function using the project's existing test framework and conventions.
---
You are writing unit tests for a software project. Follow these steps exactly:
1. Read the target file provided by the user (or inferred from context).
2. Identify the exported functions, classes, or components that need test coverage.
3. Check the existing test files in the project to determine:
- The test framework in use (Jest, Vitest, Pytest, etc.)
- The file naming convention (e.g., `*.test.ts`, `*_test.py`)
- Any shared fixtures, mocks, or helper utilities already defined
4. Write tests that cover:
- The happy path for each function
- At least one edge case per function (empty input, null, boundary values)
- Any error-handling branches
5. Place the new test file in the correct directory, matching existing conventions.
6. Do not modify the source file under any circumstances.
7. After writing the tests, print a one-line summary: how many tests were added and which file they target.
Output format: a single new test file, complete and ready to run.
Notice what makes this skill effective:
- The
nameis lowercase and hyphen-separated — this becomes the slash command (/write-tests). - The
descriptionis specific enough that Claude Code knows when to trigger it automatically, but concise enough to scan at a glance. - The body uses numbered, imperative steps — no vague suggestions, only direct instructions.
- Scope is explicitly bounded: "Do not modify the source file" prevents unintended side effects.
Step-by-Step: Creating Your First Skill
1. Create the commands directory
For a project-level skill, create the folder at the root of your repository:
mkdir -p .claude/commands
For a global skill available in every project:
mkdir -p ~/.claude/commands
2. Write the skill file
Create a new .md file. The filename becomes the command name, so choose something short and memorable:
touch .claude/commands/write-tests.md
Open the file and add your frontmatter and instruction body, following the structure shown above.
3. Invoke the skill in Claude Code
Once the file exists, you can use it immediately. In your Claude Code session, type:
/write-tests src/utils/formatDate.ts
Claude Code reads the skill, merges your argument with the instructions, and executes the workflow. No restart required — skills are loaded on every invocation.
Best Practices for Writing High-Quality Skills
Getting the file structure right is the easy part. Writing instructions that actually produce consistent, high-quality output requires a bit of discipline.
Be specific, not general. A skill named do-stuff with a body that says "help the user" will produce unpredictable results. The more precisely you define the task, the more reliable the output. Specify input format, output format, file locations, and constraints.
One skill, one job. Resist the urge to bundle "write tests AND update the README AND open a PR" into a single skill. Small, focused skills are easier to test, easier to debug, and easier to compose. If you need a multi-step workflow, chain separate skills explicitly.
Use imperatives throughout. Every instruction should start with a verb: "Read", "Check", "Write", "Print", "Do not". Avoid hedging language like "you might want to" or "consider checking" — Claude Code treats those as optional, and they will be skipped under pressure.
Define the output format explicitly. Always tell Claude Code what it should produce and where it should put it. "Output a single file at <original-filename>.test.ts" is unambiguous. "Write some tests" is not.
Add a constraint section. List what the skill should not do. Constraints prevent overreach and keep skills predictable — especially important for skills that write or delete files.
Test with edge cases. Run your skill on an empty file, a file with no exports, a file that already has tests. A good skill handles these gracefully (or exits cleanly with an informative message) rather than silently producing broken output.
Organizing a Skills Library
Once you have more than a handful of skills, organization matters. A practical structure for a mid-sized project might look like this:
.claude/
commands/
# Development
write-tests.md
fix-bug.md
refactor.md
# Review
review-pr.md
check-types.md
# Documentation
write-jsdoc.md
update-readme.md
# Deployment
pre-deploy-checklist.md
Group skills by domain and keep the names consistent. If your team uses a prefix convention (e.g., test-*, doc-*, deploy-*), stick to it — it makes tab-completion far more useful.
You can also commit your .claude/commands/ directory to version control. This means every developer who clones the repo automatically gets the full skills library. Code review for skills works exactly like code review for any other file — diff the .md, discuss the instructions, merge when ready.
Common Mistakes to Avoid
Putting too much in the description. The description field is used by Claude Code to decide when to trigger a skill automatically in agentic workflows. Keep it to one sentence that describes the trigger condition, not the implementation.
Writing explanatory prose instead of instructions. Skills are not documentation. They are directives. If you find yourself writing "This skill works by first analyzing..." — stop and rewrite it as "Read the file. Identify...".
Forgetting to constrain file writes. Any skill that creates or modifies files should explicitly list which paths are allowed. Without constraints, a broadly-worded skill can cascade into unintended changes across your project.
Making skills too long. A skill longer than 150 lines is a signal that it's trying to do too much. Break it up. Shorter skills are faster to execute, easier to reason about, and produce more predictable output.
From Manual Prompts to a Full Skills Library
The payoff from investing time in well-crafted skills is compounding. The first skill you write saves you from typing the same prompt for the hundredth time. The tenth skill you write starts to feel like a custom IDE extension. A full library of 20-30 skills tailored to your stack transforms Claude Code from a chat assistant into a programmable development partner.
The best place to start: pick the task you ask Claude Code to do most often, write a skill for it today, and refine it over the next week of real use. Within a month, you'll have the foundation of a skills library that encodes everything your team knows about how to work well.
Ready to build your first skill but not sure where to start? SkillMinter generates complete, ready-to-download Claude Code skill files from a plain-language description of what you want to automate — no prompt engineering expertise required. Describe your workflow, get a production-ready .md file in seconds.