Skip to content
Claude Code Docs Claude Code Docs

Your First Skill

A skill is a custom slash command you write as a markdown file. When you type /my-skill in Claude Code, Claude reads that file and uses it as instructions for the task. Skills are great for repeating workflows: code reviews, commit message formatting, documentation generation, or anything you do more than once.

Quick version: Create a file at .claude/skills/my-skill/SKILL.md with YAML frontmatter at the top, write your instructions, and type /my-skill to use it.

  1. Create the skill file

    Create this directory structure in your project:

    your-project/
    └── .claude/
        └── skills/
            └── my-first-skill/
                └── SKILL.md

    Create .claude/skills/my-first-skill/SKILL.md with this content:

    ---
    name: my-first-skill
    description: Summarizes the current git diff in plain English
    user-invocable: "true"
    ---
    

    Please summarize the current `git diff` output in plain English. Focus on:
    - What files changed
    - What the change does (not how)
    - Whether anything looks risky
    

    Keep the summary under 5 bullet points.

  2. Understand the frontmatter fields

    The section between --- markers is YAML frontmatter. It tells Claude Code how to load and expose the skill.

    FieldWhat it does
    nameThe slug used for the slash command. Must be lowercase with hyphens only.
    descriptionShown when Claude decides whether to invoke this skill automatically.
    user-invocableSet to "true" (with quotes!) to make it available as /my-first-skill.

  3. Invoke the skill

    Restart your Claude Code session (or type /reload), then type:

    /my-first-skill

    Claude will run a git diff, then summarize it according to your instructions.

How skill discovery works

Section titled “How skill discovery works”

When you type /my-first-skill, here is what Claude Code does:

  1. Scans skills directories — Claude Code walks .claude/skills/ in your project, then ~/.claude/skills/ in your home directory, then any plugin skills, looking for SKILL.md files.

  2. Parses the frontmatter — For each file found, Claude Code reads the name, description, and user-invocable fields.

  3. Matches your slash command — /my-first-skill is matched to the skill whose name is my-first-skill.

  4. Injects the skill instructions — The body of SKILL.md (everything below the --- frontmatter fence) is injected into Claude’s context window as instructions.

  5. Claude executes — Claude reads the instructions and responds using available tools.

Skills are scanned from these locations (in priority order):

  1. .claude/skills/ in your current project
  2. ~/.claude/skills/ in your home directory (shared across all projects)
  3. Plugin skills (if you have plugins installed)

Minimum viable frontmatter

Section titled “Minimum viable frontmatter”

The only required field is name. Everything else has a default:

---
name: my-skill
---

This creates a skill named my-skill that Claude can invoke automatically (but you can’t type /my-skill — for that you need user-invocable: "true").

Common skill patterns

Section titled “Common skill patterns”

Skills with arguments

Section titled “Skills with arguments”
---
name: explain-function
description: Explains what a function does
argument-hint: <function-name>
user-invocable: "true"
---


Explain the function named `$ARGUMENTS` in the current file. Cover:
- What it does
- What each parameter means
- What it returns
- Any edge cases

Use: /explain-function calculateTax

Skills that only Claude can invoke (not you)

Section titled “Skills that only Claude can invoke (not you)”
---
name: check-style
description: Checks code for style violations before every commit
user-invocable: "false"
---


Review the staged changes for style violations...

With user-invocable: "false", Claude decides when to invoke this automatically. You can’t call it with /check-style.

Skills limited to specific tools

Section titled “Skills limited to specific tools”
---
name: safe-review
description: Reviews code without running any commands
allowed-tools: Read, Glob, Grep
user-invocable: "true"
---


Review the code changes without executing any commands. Read-only analysis only.

Troubleshooting

Section titled “Troubleshooting”

Skill doesn’t appear in the / menu

  • Check user-invocable: "true" — make sure the value has quotes
  • Restart Claude or type /reload
  • Check for YAML syntax errors (colons, indentation)

Skill appears but does nothing useful

  • The instructions after the frontmatter are just markdown — Claude reads them as a prompt
  • Make them specific: “Do X, then Y, then output Z” works better than “Help with X”

Skill runs but ignores my allowed-tools restriction

  • allowed-tools limits which tools Claude can use in this skill, not which ones it will use
  • If you need strict isolation, combine with a permission rule

Next steps

Section titled “Next steps”

← Back to GettingStarted/README.md