How to Add Skills to Claude Code

Adding skills to Claude Code lets you extend its built-in capabilities with custom, reusable instructions and workflows. Skills are essentially folders containing a SKILL.md file (and optional scripts or resources) that Claude can load on demand to handle specific tasks like code review, data analysis, or project setup. This guide walks you through creating and installing skills, so you can tailor Claude Code to your workflow.

What You’ll Need

• Claude Code installed and authenticated (via the Claude API or a Claude subscription).
• Access to your project directory or the global Claude configuration folder (~/.claude/skills on macOS/Linux, %USERPROFILE%\.claude\skills on Windows).
• A text editor to create the skill files.
• Basic familiarity with Markdown and command-line tools (optional for scripts).

Step-by-Step

1. Understand the skill structure. A skill is a folder with a SKILL.md file that contains frontmatter (name, description) and the instruction body. You can also include helper scripts or reference files in the same folder.
2. Create the skill folder. Navigate to your project’s .claude/skills directory (create it if missing) or the global ~/.claude/skills folder. For a project-specific skill, use mkdir .claude/skills/my-skill.
3. Write the SKILL.md file. Inside the folder, create a file named SKILL.md. Start with YAML frontmatter:

   ---
   name: my-skill
   description: Use this skill when the user asks to summarize a codebase or generate a README.
   ---

   The description is crucial—it tells Claude when to invoke the skill.

4. Add the instruction body. Below the frontmatter, write clear, step-by-step instructions. Use Markdown headings, bullet points, and code blocks. For example:

   # Codebase Summarizer
   
   1. List all files in the project root.
   2. Read the main entry point and configuration files.
   3. Produce a summary with sections: Overview, Tech Stack, and Key Modules.
   4. Output the summary in Markdown.

   Be specific about what Claude should do and in what order.

5. Include helper scripts (optional). If your skill needs a script, place it in the same folder (e.g., analyze.py) and reference it in the instructions: Run "python analyze.py" from the skill directory. Claude will locate the script relative to the SKILL.md file.
6. Save and test. Save the file. In Claude Code, start a new session and ask something that matches your skill’s description. For example, “Summarize this project.” Claude should automatically load the skill and follow its instructions.
7. Debug if not triggered. If Claude doesn’t pick up the skill, try explicitly saying “Use the my-skill skill” to force it. If that fails, check the skill folder path and the frontmatter syntax.
8. Share or sync skills. To use the same skill across projects, place it in the global ~/.claude/skills folder. You can also version-control your skills in a repository and symlink them into projects.

Common Mistakes

• Missing or incorrect frontmatter. The name and description fields are required. A typo in the YAML (like a missing colon) will break the skill.
• Vague descriptions. If the description doesn’t clearly state when to use the skill, Claude may never invoke it. Use concrete triggers like “when the user asks to generate a test plan.”
• Wrong folder location. Placing the skill in a random directory instead of .claude/skills means Claude won’t see it.
• Overly long instructions. Keep the body concise and action-oriented. Long, rambling instructions are harder for Claude to follow precisely.
• Forgetting to restart. After adding a skill, you may need to restart Claude Code or start a new session for it to pick up the change.

Tips

• Use a descriptive name. The skill name should be short and memorable, like code-review or api-docs.
• Leverage the description for triggering. Include synonyms and edge cases: “Use for summarizing, outlining, or explaining a codebase.”
• Test with a simple prompt first. Before complex tasks, ask Claude to “List the steps of the my-skill skill” to verify it loads correctly.
• Keep scripts self-contained. If your skill uses a script, make sure it doesn’t rely on external dependencies that aren’t installed.
• Version your skills. Use Git to track changes, especially if you share skills across a team.

Troubleshooting

• Skill not recognized. Run claude in the project directory and type /skills to list available skills. If yours isn’t there, check the folder path and the frontmatter.
• Claude ignores the skill. Try explicitly saying “Use the [skill name] skill” in your prompt. If that works, refine the description to be more specific.
• Script errors. If a referenced script fails, ensure the path is correct relative to the SKILL.md file. Test the script manually in a terminal first.
• Skill loads but doesn’t follow instructions. Review the instruction body for ambiguity. Break it into numbered steps and specify output format.
• Changes not taking effect. Restart Claude Code completely. Some versions cache skill metadata at startup.

Frequently Asked Questions

Can I add skills without writing code?

Yes. A skill is just a Markdown file with instructions. No programming is required for basic skills.

Where are skills stored globally?

In ~/.claude/skills on macOS/Linux or %USERPROFILE%\.claude\skills on Windows.

Can a skill run shell commands?

Yes, by including a script (e.g., a Bash or Python file) and instructing Claude to execute it. Claude will run it in its sandboxed environment.

How do I update a skill?

Edit the SKILL.md file and restart Claude Code. The new version will be used in new sessions.

Can I share skills with my team?

Yes. Store skills in a Git repository and have team members clone or symlink them into their .claude/skills folder.

Do skills work with Claude Code on Windows?

Yes, as long as you use the correct path (%USERPROFILE%\.claude\skills) and ensure any scripts are compatible with your shell.

Related

• VMware Shared Folder: Setup and Use Guide
• Run Java Bytecode Across Platforms with the JVM?
• DOSBox Framerate & Display Troubleshooting