How to install Claude Code skills

Installing an Agent Skill is mostly a matter of putting a folder in the right place. The friction is usually in the parts around that: choosing which method fits, checking what you are about to trust, and working out why a skill is not firing.

This guide covers all three.

Before you install: a two-minute review

A skill is a set of instructions handed to an agent that writes code on your behalf, and some skills bundle scripts they tell the agent to run. That deserves the same scrutiny you would give any dependency.

Open the repository and check:

1. Read SKILL.md end to end. It is usually under 200 lines. You are looking for anything that touches credentials, deletes files, or contacts external services.
2. List the other files. If the skill ships scripts, skim them.
3. Check the licence. About a third of the public skills we index declare none, which leaves you no clear footing to adapt or redistribute them.
4. Check the last commit. A skill written against an API that changed a year ago will confidently supply wrong information.

Every listing in our catalog surfaces the licence, star count, and last update date, and links to the source — the point is to make this check quick, not to replace it.

Method 1: install a plugin from a marketplace

Most larger skill collections ship as plugins. This is the least manual route and the easiest to reverse.

Add the marketplace, then install from it:

# In Claude Code
/plugin marketplace add owner/repository
/plugin install plugin-name

Every skill page in our catalog shows the exact command for that project, because the repository and plugin names differ per publisher.

Plugins can bundle more than skills — commands, agents, hooks, even MCP servers — so you may be installing more than you expect. The plugin’s README should say what is inside.

To remove it, uninstall the plugin rather than deleting individual folders, so nothing is left behind:

/plugin uninstall plugin-name

Method 2: install a single skill manually

When you want one skill rather than a whole collection, copy the folder yourself.

Personal skills go in your home directory and apply to every project:

mkdir -p ~/.claude/skills
git clone https://github.com/owner/repository /tmp/skill-src
cp -r /tmp/skill-src/skills/the-skill-you-want ~/.claude/skills/
rm -rf /tmp/skill-src

The result should look like this:

~/.claude/skills/
└── the-skill-you-want/
    ├── SKILL.md          ← required
    └── reference.md      ← optional supporting files

The only hard requirement is that SKILL.md sits directly inside a folder under skills/. Nesting it one level deeper is the most common reason a manual install appears to do nothing.

Method 3: install a skill for one project

Project-scoped skills are the ones worth caring about if you work on a team. They live in the repository and travel with it:

mkdir -p .claude/skills
cp -r /path/to/the-skill .claude/skills/
git add .claude/skills && git commit -m "chore: add testing conventions skill"

Now every engineer who clones the repository gets the same conventions automatically, including the one who joins next month. This is the single most useful thing you can do with skills as a team: move conventions out of one senior developer’s head and into something the agent applies on its own.

Use project scope for anything team-specific — architecture rules, deployment steps, review standards. Use personal scope for your own habits.

Verifying it worked

Two checks, in order.

Is it discoverable? Ask the agent what skills it has available. If yours is not listed, the problem is the file layout — check that SKILL.md is directly inside a folder in skills/, and that the frontmatter has both name and description.

Does it fire? Give the agent a task that clearly matches the skill’s purpose and watch whether the behaviour changes.

If the skill is listed but never activates, the description is the culprit almost every time. At rest the agent only holds each skill’s name and description; it matches your request against those to decide what to load. A description that does not name the triggering situations gives it nothing to match on:

# Never fires — nothing to match against
description: Helps with testing.

# Fires reliably — names the situations explicitly
description: >
  Testing conventions for this repository, including file layout, mocking
  policy, and the coverage gate. Use when writing new tests, fixing failing
  tests, or reviewing test coverage.

Rewrite the description as a list of situations where the skill should apply. That fixes the large majority of “installed but nothing happens” reports.

Troubleshooting

Skill does not appear at all. SKILL.md is nested too deep, or the frontmatter is malformed. YAML is whitespace-sensitive; a stray tab will invalidate the block silently.

Skill appears but never activates. Description problem — see above.

Two skills conflict. Narrow both descriptions so their trigger conditions do not overlap, or remove the one you use less. Broad skills that try to cover a whole language or framework are the usual offenders.

Skill fires when it should not. The description is too broad. Add the boundary explicitly: “Use for Python projects only”, “Do not use for one-off scripts.”

Where to find skills worth installing

The catalog indexes public, open-source skills from GitHub with licence, popularity, and freshness on every listing. If you would rather start from a shortlist:

• Best workflow skills — planning, orchestration, multi-step tasks
• Best testing skills — test generation, coverage, QA
• Best security skills — auditing, secrets, vulnerability scanning
• Best DevOps skills — CI/CD, containers, deployment
• Trending now — what is gaining traction this week

Start with one or two that address something you are actually repeating. A library you assembled speculatively is one you will not maintain.