The quick answer
Create a folder for your Skill under .claude/skills/ in your project, or under ~/.claude/skills/ for a personal Skill, and add a SKILL.md file inside it. In Claude Code, type / to browse available commands and Skills, then invoke yours with / followed by its name. You can also describe a relevant task and let Claude use the Skill when appropriate. (code.claude.com)
1. Create a Skill
For a project-specific Skill, use a folder like this at your repository root:
your-project/
└── .claude/
└── skills/
└── review-tests/
└── SKILL.md
For a personal Skill available across projects, use ~/.claude/skills/review-tests/SKILL.md. Claude Code reads Skills from project and home-directory configuration; project files can be shared through the repository, while ~/.claude is personal configuration. (code.claude.com)
Put the Skill’s instructions in SKILL.md. Frontmatter is optional in Claude Code; this example includes name and description to label the Skill and describe when it is useful. The folder name and frontmatter name match here. The documentation supports invoking Skills as /skill-name; if you choose different folder and frontmatter names, check the current naming reference rather than assuming which one takes precedence. (code.claude.com)
---
name: review-tests
description: Review code changes for missing or weak tests. Use when reviewing a diff or preparing a change for review.
---
When reviewing a change:
1. Identify the behavior the change adds or alters.
2. Check whether tests cover the expected behavior and important edge cases.
3. Run relevant existing tests if asked and if the project setup allows it.
4. Report specific gaps and point to the affected files. Do not claim a test passed unless you ran it.
This is an illustrative Skill, not a test of Claude Code. A Skill is a SKILL.md file with instructions; it can also have a directory for supporting files. (code.claude.com)
2. Find and invoke the Skill
In a Claude Code session, type / to see available commands and Skills. Type /review to filter the menu, then choose the Skill. Or invoke it directly at the start of your message:
/review-tests Review the changes in this branch for missing test coverage.
Claude Code documents direct slash-command invocation as well as automatic use when a Skill is relevant. Direct invocation is a straightforward way to check whether Claude Code recognizes it; commands are recognized at the start of a message. (code.claude.com)
3. Check the result and troubleshoot
For this example, check whether the review identifies the changed behavior, considers test coverage, and reports concrete gaps. Verify any claimed test results yourself or ask Claude to run the relevant project test command. A plausible response does not prove every instruction was followed or that a test passed.
If the Skill is missing from the / menu, check that SKILL.md is spelled and placed correctly inside its Skill folder under a supported Skills directory. Then run /reload-skills to rescan Skill directories and check the menu again. If the Skill appears but the response misses an instruction, recognition worked; revise the description or instructions and try a more specific task. (code.claude.com)
When to use a Skill
Use a Skill for a checklist, domain guidance, or procedure you repeat. Claude Code’s documentation suggests creating one when you keep repeating instructions or when a section of CLAUDE.md has become a procedure rather than a fact. Unlike CLAUDE.md content, a Skill’s body loads when the Skill is used. (code.claude.com)
What changes when you use the Claude API?
A local Claude Code Skill does not automatically configure a Claude API request. The Messages API has a separate Skills integration: you identify Skills in the request’s container configuration, and they run through the code execution tool. Custom API Skills are managed through the Skills API; the local Claude Code folder is not itself an uploaded API Skill. (platform.claude.com)
For API use, follow the API Skills guide: it requires an API key and the code execution tool, and says to use a model that supports that tool. The guide allows up to 20 Skills per request. This is a separate integration path from invoking /skill-name in a Claude Code session. (platform.claude.com)
Sources
Extend Claude with skills — Claude Code Docs
Explore the .claude directory — Claude Code Docs
Extend agents with skills — Claude Code Docs