Skip to content
Recaply.
Sign inSubmit a tool

LearnTutorials

Claude CodeTutorialsOpen Claude Code

Install agent skills in Claude Code

Add a skill to Claude Code with one npx line or a premium ZIP, check it with /skills and run it with /skill-name. Covers personal and project folders.

By Recaply EditorsBeginner5 min6 stepsUpdated

A hand drops a card into an open desk drawer

Claude Code reads skills from two folders you control: .claude/skills in a project and ~/.claude/skills in your home folder. Each skill is its own folder with a SKILL.md file inside.

Short answer: run the skill's npx line in your project (or unzip a premium skill into .claude/skills), type /skills to see it, then type /skill-name or just ask for the job.

What you need

  1. Step 1: Choose a project or personal skill

    1 min

    Where the folder goes decides which sessions can use it.

    1. Project: .claude/skills/<skill-name>/SKILL.md in your repo. Sessions in this repo load it, and your team gets it when you commit it.
    2. Personal: ~/.claude/skills/<skill-name>/SKILL.md. Every project on this computer loads it.
    3. Claude Code also loads .claude/skills/ in parent folders up to the repo root, so a skill at the root works when you start in packages/app/ too.

    Same name in both? The personal skill runs. Skills your organization deploys beat both. Personal skills don't load in Cowork or cloud sessions.

  2. Step 2: Install a free skill with one line

    1 min

    The skills CLI copies the skill from its maker's GitHub repo into .claude/skills/.

    1. Open a terminal in your project folder.
    2. Paste the line from the skill's Recaply page. It ends in -a claude-code.
    3. To install it for all your projects instead, add -g. It then goes to ~/.claude/skills/.
    The install line
    npx skills add <owner>/<repo> --skill <skill-name> -a claude-code

    You should see a new .claude/skills/<skill-name>/ folder with SKILL.md inside.

    The CLI asks which agents to install to?

    The line is missing its -a value. Pick your agent in the list, or run the line again with it. Add -y to skip the questions.

    The CLI keeps its main copy in .agents/skills/ and links .claude/skills/<skill-name> to it, so keep both folders. Add --copy if you want a plain copy instead of a link.

  3. Step 3: Or install a premium skill from its ZIP

    2 min

    A premium skill's ZIP holds one folder named after the skill, ready to drop in.

    1. On the skill's Recaply page, sign in, buy it (or use the plan), then click Download ZIP.
    2. Move the ZIP into your project folder and open a terminal there.
    3. Run the line below. For all your projects, unzip to ~/.claude/skills/ instead.
    Your line
    unzip <slug>.zip -d .claude/skills/

    You should see .claude/skills/<slug>/SKILL.md, with the skill's other files beside it.

    On Windows, there's no unzip?

    Right-click the ZIP, choose Extract All, and move the extracted folder into the .claude/skills folder in your project.

    The path must be .claude/skills/<slug>/SKILL.md. If you see <slug>/<slug>/, move the inner folder up one level.

  4. Step 4: Check that Claude Code sees it

    1 min

    Claude Code watches its skills folders, so a new skill shows up in a running session without a restart.

    1. In Claude Code, type /skills. Type part of the name to filter the list.
    2. Or ask Claude: What skills are available?
    3. If .claude/skills/ didn't exist when the session started, run /reload-skills so Claude Code finds the new folder.

    You should see the skill's name and description in the list.

    It's in the folder but not in the list?

    Run claude plugin validate .claude/skills (or ~/.claude/skills) to find a SKILL.md whose top block doesn't parse. It needs Claude Code v2.1.233 or later.

    In the /skills list, press Space or Enter on a skill to change whether Claude and the / menu can use it, and Esc to save.

  5. Step 5: Run the skill

    1 min

    Claude loads a skill when your request fits its description, or right away when you call it.

    1. Type / and the skill's name, then what you want. The text after the name goes to the skill.
    2. Or ask for the job in plain words that match the skill's description.
    Your prompt
    /<skill-name> <what you want it to do>

    You should see Claude follow the skill's steps for your task.

    Claude doesn't use the skill on its own?

    Use words from its description, or call it with /skill-name. If the top block of SKILL.md is broken, /skill-name still works but Claude can't match the description; start claude --debug to see the error.

  6. Step 6: Not working? Check these

    2 min

    Most problems come from where the folder sits, its name, or the block at the top of SKILL.md.

    1. The path is .claude/skills/<skill-name>/SKILL.md: one folder deep, and the file named SKILL.md.
    2. Two skills share a name? The one in ~/.claude/skills/ runs, not the project's.
    3. Started Claude Code somewhere else? Project skills load from where you start it and the folders above it, up to the repo root. Skills in a subfolder load once Claude reads or edits a file there.
    4. Lots of skills? Claude Code may drop some descriptions to fit its budget. Run /doctor to see the cost and /skill-doctor to find skills to turn off.
    5. Personal skills gone? Look in ~/.claude/skills/.trash/ and move the folder back.

    Signed in with a claude.ai account? Skills you turn on at claude.ai sync to ~/.claude/skills/synced/ and show under claude.ai sync in /skills.

You get

A skill in Claude Code that shows in /skills and runs with /skill-name

Try next

Install an agent skill in any AI coding agent6 steps · 5 minInstall agent skills in OpenCode6 steps · 5 minInstall agent skills in GitHub Copilot6 steps · 5 min

Did this guide work for you?

Sources

0 of 6Next: Choose a project or personal skill