Quick Start: Claude Code Skills

Use Claude Code skills when you want Claude Code to apply a reusable local workflow, load task-specific instructions only when needed, or expose a repeatable command such as /summarize-changes, /deploy, or /review-pr.

For Claude Desktop or Claude on the web skills managed through Customize > Skills, see the Claude Skills quick start.

For the official reference, see Extend Claude with skills in the Claude Code docs.

What a Claude Code skill is

A skill is a directory with a required SKILL.md file and optional supporting files:

my-skill/
  SKILL.md
  reference.md
  examples/
  scripts/

Claude sees each skill's name, description, and path up front. The full SKILL.md body loads only when Claude invokes the skill or you invoke it directly with /skill-name.

Skills are the recommended replacement for most custom commands. Existing .claude/commands/ files still work, but a skill with the same name takes precedence.

Install a personal skill

Use personal skills for workflows you want across all projects.

mkdir -p ~/.claude/skills/summarize-changes

Create ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

Current changes:

!`git diff HEAD`

Instructions:

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

Start Claude Code in a git project and test it two ways:

What did I change?

Or invoke it directly:

/summarize-changes

Install a project skill

Use project skills when the workflow belongs with the repository and should be shared with the team.

.claude/skills//SKILL.md

Example:

mkdir -p .claude/skills/release-checklist

Project skills load from .claude/skills/ in the starting directory and parent directories up to the repository root. Claude Code can also discover nested .claude/skills/ directories as you work in subdirectories, which is useful for monorepos.

Skill locations

When skills share a name across levels, enterprise overrides personal, and personal overrides project. Plugin skills use a plugin-name:skill-name namespace.

Claude Code watches existing skill directories for changes. If you add, edit, or remove a skill in an already-watched directory, the change takes effect in the current session. If you create a top-level skills directory after Claude Code has started, restart Claude Code.

Frontmatter basics

SKILL.md starts with YAML frontmatter. Only description is recommended, but additional fields control invocation, arguments, tools, model choice, and execution context.

---
name: deploy
description: Deploy the application to production
argument-hint: "[environment]"
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(npm test *) Bash(npm run build *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite.
2. Build the application.
3. Push to the deployment target.
4. Verify the deployment succeeded.

Useful fields:

Control invocation

By default, both you and Claude can invoke a skill:

• You can type /skill-name.
• Claude can load the skill automatically when your request matches the description.

Use disable-model-invocation: true for workflows with side effects, such as deploys, commits, or messages. Use user-invocable: false for background knowledge that Claude may use automatically but users should not run as a command.

Pass arguments

Claude Code passes text after the skill name into $ARGUMENTS.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Invocation:

/fix-issue 123

For positional values, use $ARGUMENTS[0], $ARGUMENTS[1], or shorthand values like $0 and $1.

Add dynamic context

Inline shell injection runs a shell command before Claude sees the skill. The command output replaces the placeholder in the rendered skill.

Pull request context:

- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Use dynamic context for live diffs, issue data, environment details, or generated reports. To disable shell execution for user, project, plugin, or additional-directory skills, set disableSkillShellExecution in Claude Code settings.

Pre-approve tools carefully

The allowed-tools field lets Claude use listed tools without per-use approval while the skill is active. It does not restrict all other tools; your normal permission settings still apply.

Review project skills before trusting a repository. A project skill can grant broad tool access after you accept the workspace trust dialog.

Override visibility

Use /skills to manage skill visibility. Highlight a skill, press Space to cycle states, then press Enter to save to .claude/settings.local.json.

The underlying setting is skillOverrides:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

States include:

Plugin skills are managed through /plugin, not skillOverrides.

Share skills

Share skills at the scope that matches the audience:

• Project: Commit .claude/skills/ to version control.
• Plugin: Create a skills/ directory in a Claude Code plugin.
• Managed: Deploy organization-wide through managed settings.

Verify a skill

After installing a skill:

1. Run Claude Code in a project where the skill should be available.
2. Type / and confirm the skill appears.
3. Invoke it directly with /skill-name.
4. Ask a natural-language request that should match the skill description.
5. If Claude does not select it, tighten the description and when_to_use fields.

For MCP setup in Claude Code, see the Claude quick start.