# Quick Start: Claude Code Skills

Canonical page: https://www.kuudo.com/docs/quick-start/claude-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](/docs/quick-start/claude-app-skills/).

For the official reference, see [Extend Claude with skills in the Claude Code docs](https://code.claude.com/docs/en/skills).

## What a Claude Code skill is

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

```text
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.

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

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

```markdown
---
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:

```text
What did I change?
```

Or invoke it directly:

```text
/summarize-changes
```

## Install a project skill

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

```text
.claude/skills/<skill-name>/SKILL.md
```

Example:

```bash
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

| Scope | Path | Applies to |
| --- | --- | --- |
| Enterprise | Managed settings | All users in the organization. |
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects. |
| Project | `.claude/skills/<skill-name>/SKILL.md` | The current project. |
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the plugin is enabled. |

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.

```markdown
---
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:

| Field | Use |
| --- | --- |
| `name` | Display name. If omitted, Claude uses the directory name. |
| `description` | What the skill does and when Claude should use it. |
| `when_to_use` | Extra trigger guidance appended to the description. |
| `argument-hint` | Autocomplete hint for expected arguments. |
| `arguments` | Named positional arguments for substitutions. |
| `disable-model-invocation` | Set `true` when only the user should trigger the skill manually. |
| `user-invocable` | Set `false` to hide background knowledge from the `/` menu. |
| `allowed-tools` | Tools Claude may use without asking while the skill is active. |
| `paths` | File globs that limit automatic activation. |
| `context` | Set `fork` to run the skill in a subagent context. |
| `agent` | Subagent type to use when `context: fork` is set. |

## 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`.

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

Fix GitHub issue $ARGUMENTS following our coding standards.
```

Invocation:

```text
/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.

```markdown
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`:

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

States include:

| State | Listed to Claude | In `/` menu |
| --- | --- | --- |
| `on` | Name and description | Yes |
| `name-only` | Name only | Yes |
| `user-invocable-only` | Hidden | Yes |
| `off` | Hidden | Hidden |

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 Code MCP quick start](/docs/quick-start/claude-code-mcp/).