How to Import a Claude Skill

A skill is a reusable prompt packaged as a Markdown file with a bit of frontmatter. Someone writes it once, shares the file, and anyone can plug it into their own Claude setup. This tutorial covers both ways to import one: through the Claude Desktop interface (easier, no command line), and by placing the file yourself for Claude Code (what you want when working in a project).

---

Before you start: check the file's frontmatter

Every skill file needs a frontmatter block at the top with at least a name and a description:

---
name: security-review
description: Audit the current branch for injection bugs, auth bypasses, and secret leakage. Use when the user asks for a security review or to audit changes.
---

You are a senior security engineer...

If the name field is missing, the import will fail with an error like "missing field 'name' in SKILL.md frontmatter and no directory name available for fallback." This is the single most common reason a shared skill refuses to install. Open the file in any text editor, add the missing field (usually matching the filename), and you are good to go.

While you are in there, make sure the description ends with a few concrete trigger phrases — that is what Claude reads when deciding whether to invoke the skill automatically. Without them, the skill will only fire when you call it by name.

---

Method 1 — Import through the Claude Desktop UI

This is the easiest path if you are working with Claude on the web or in the desktop app. No terminal, no filesystem paths.

Step 1 — Open the Customize page

In the Claude side menu, click Customize. This opens the settings page where you manage skills, projects, and preferences.

Step 2 — Go to the Skills tab

In the side menu of the Customize page, click Skills. Claude shows the list of skills already installed for your account.

Step 3 — Create a new skill from the file

Above the list of existing skills, there is a + button. Click it, then choose:

Create skill → Upload a skill

A file picker opens. Select the .md file you were given. Claude parses the frontmatter and registers the skill.

If the import succeeds, the skill appears in the list. If it fails, Claude shows the parser error — usually either the missing name field mentioned above, or a malformed frontmatter block (broken indentation, missing --- delimiters).

Step 4 — Test it before relying on it

Open the new skill in the list, click the three-dots menu in the top-right, and choose Test skill. This opens an isolated test session with only that skill loaded, so you can verify the output matches what the author described before letting it loose in your normal chats.

---

Method 2 — Install for Claude Code

If the skill is meant to run in your terminal inside a project (which is the common case when the skill operates on code), you install it by placing the file in the right folder.

Step 1 — Pick project-level or user-level

Claude Code looks for skills in two places:

• Project-level — .claude/commands/ inside the project folder. The skill is only available when you run Claude Code in that project. Good for skills specific to one codebase, and for skills you want to commit alongside the repo.
• User-level — ~/.claude/commands/ in your home directory. The skill is available in every project on your machine. Good for personal utilities that do not depend on a particular codebase.

If both levels have a skill with the same filename, the project-level one wins.

Step 2 — Create the directory if it does not exist

For a project-level skill:

mkdir -p .claude/commands

For a user-level skill:

mkdir -p ~/.claude/commands

Step 3 — Copy the skill file into the right folder

The filename (minus .md) becomes the slash command name. security-review.md is invoked as /security-review.

cp ~/Downloads/security-review.md .claude/commands/

If the skill lives in another repo you have cloned locally:

cp path/to/other-repo/.claude/commands/security-review.md .claude/commands/

Step 4 — Verify it loaded

Start (or restart) a Claude Code session in your project. Type / and wait for the autocomplete — every loaded skill shows up in that list. If yours is there, it is ready.

Invoke it:

/security-review

If the skill accepts arguments through $ARGUMENTS, pass them after the command name:

/explain the retry logic in src/client.js

Step 5 — Keep it up to date

If the skill came from a team repo, the simplest workflow is to commit .claude/commands/ and pull updates as the author revises the file — the same way you stay in sync with any other checked-in code.

If the file was shared directly, replace it with the newer version when the author sends an update:

cp ~/Downloads/security-review-v2.md .claude/commands/security-review.md

---

Troubleshooting

"Missing field 'name' in SKILL.md frontmatter" — the skill file has no name: line in its frontmatter. Open the file, add it (match the filename for consistency), save, and re-import.

Skill does not appear in / autocomplete (Claude Code) — check the file has a .md extension and lives in the correct commands/ directory. Restart the Claude Code session; new skills are loaded at session start, not mid-conversation.

Skill imports but Claude never invokes it automatically — the description field is what Claude reads when deciding whether to auto-fire. If it is vague, Claude will not pick it up. Either describe the task in the skill's own vocabulary when prompting, or edit the description to include concrete trigger phrases. There is a dedicated tutorial elsewhere in this section that goes deeper into getting Claude to actually use the skills you install.

Conflicting skill names — in Claude Code, a project-level skill and a user-level skill with the same filename both exist, and the project-level one always wins. If you edited the user-level one and nothing changed, look for an older copy in .claude/commands/ inside the current project.

Upload fails silently in Claude Desktop — this is almost always a frontmatter formatting issue: a stray tab instead of spaces, missing --- delimiters, or characters that YAML cannot parse (unescaped colons in a single-line string, for example). Opening the file in a YAML-aware editor quickly surfaces the bad line.