To add a skill to Claude Code, put a SKILL.md file inside a named skill folder under either your project’s .claude/skills/ directory or your personal ~/.claude/skills/ directory. Project skills are stored with the repository; personal skills are stored in your home directory for use across projects. Include frontmatter and the instructions Claude should follow. Start Claude Code in the relevant project and invoke the skill with /skill-name, or describe a task that matches its description. Claude Code can also choose relevant skills automatically. (Claude Code skills documentation; Claude Code Academy)
Create and add a skill
Choose where it should be available:
- For one project:
<your-project>/.claude/skills/<skill-name>/SKILL.md. Use this when the skill is specific to a repository or should be available to people working in that project. - For your user account:
~/.claude/skills/<skill-name>/SKILL.md. Use this when you want the skill available across your projects.
A skill is a folder, not just a loose Markdown file. The required file is SKILL.md; you can add supporting files in the folder if the instructions need them. Frontmatter can control whether you or Claude invokes a skill, and Claude can load skills automatically when relevant. (Claude Code skills documentation; Create custom skills)
Example: add a project skill
From the root of your repository, create the directory and file:
mkdir -p .claude/skills/test-check
cat > .claude/skills/test-check/SKILL.md <<'EOF'
---
name: test-check
description: Run relevant repository tests and summarize failures. Use when asked to test changes or validate a code edit.
---
# Test check
1. Inspect the repository instructions and test configuration.
2. Identify the most relevant test command for the changed code.
3. Run the test command and report the result.
4. If a test fails, summarize the failure and do not claim the change passed.
EOF
The text after the second --- is the skill’s instructions. In this example, name identifies the skill and description helps Claude decide when it is relevant. Use both in your own skill as shown; the documentation identifies SKILL.md as the required file and describes frontmatter as a place for invocation controls. Adjust the example workflow to match your repository’s actual test commands and requirements. Skills are reusable instructions and workflows; they aren’t a way to give Claude access to an external service—that calls for a different integration. (Claude Code skills documentation; Create custom skills)
Add an existing skill
Copy the whole skill folder, including its SKILL.md and any supporting files, into the project or personal skills directory above. Keep the skill’s folder name and any internal file paths consistent with its instructions. Before using a skill from someone else, review its instructions and scripts; it may contain executable or otherwise consequential content. Claude Code’s documentation describes skills as folders that can include supporting files. (Claude Code skills documentation)
Invoke and check the skill
Open Claude Code in the project where you placed a project-level skill, then type its name directly. For the example above, run:
/test-check
You can also describe a task that matches the skill’s description; Claude Code may load a relevant skill automatically. Skills can be invoked with / followed by the skill name, but frontmatter can control whether a skill is user-invocable, model-invocable, or both. If an existing skill does not respond to the invocation you expect, inspect its invocation settings rather than assuming both invocation paths are enabled. For a simple test, ask Claude to run the relevant tests, then confirm it follows the skill’s steps and reports the actual command and result. (Claude Code skills documentation)
If the skill does not appear or run as expected, check these basics first:
- Confirm the file is named exactly
SKILL.mdand is inside the named skill folder under the intended project or personal directory. - Check that the frontmatter is valid and that the example’s
nameanddescriptionaccurately identify the skill and when it applies. The documentation identifiesSKILL.mdas required; don’t assume every example frontmatter field is universally mandatory. - Check the skill’s invocation settings. Frontmatter can affect whether you can invoke it directly, whether Claude can select it automatically, or both.
- If you have just added or edited a skill and it is not visible, try checking from a fresh Claude Code session. The documentation passages cited here do not establish whether a new session or reload is required for changes to be discovered.
- Use
/contextto inspect what is in the current session’s context, including skills. (Claude Code skills documentation; Debug your configuration)
Do Claude Code skills automatically work in the production API?
No—not merely because the skill folder exists on your computer. The Claude API has a separate documented skills workflow: skills are managed through the API, then referenced in a Messages API request’s container parameter; using them requires the code execution tool. Treat a local Claude Code skill and an API-managed skill as separate setup steps, even though both use the Agent Skills approach. See Anthropic’s Using Agent Skills with the API guide for API-specific setup. (Claude Platform API skills guide)
Sources
Extend Claude with skills — Claude Code Docs
Skills — Claude Code 101 · Claude Academy
Create custom skills — Claude.ai Documentation