# How to Create Custom Skills for Claude Code: A Complete Developer Guide

> Learn to create custom skills for Claude Code by generating a skeleton editing the manifest and packaging your code. Enhance Claude's capabilities today.

- Repository: [Anthropic/skills](https://github.com/anthropics/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**You can create custom skills for Claude Code by generating a skeleton with [`init_skill.py`](https://github.com/anthropics/skills/blob/main/init_skill.py), editing the [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) manifest, and packaging the result with [`package_skill.py`](https://github.com/anthropics/skills/blob/main/package_skill.py) for installation via the Claude Code Marketplace or `/plugin` command.**

Creating custom skills for Claude Code allows you to extend the AI assistant with domain-specific workflows and automated scripts. The `anthropics/skills` repository provides a complete toolchain for authoring, validating, and packaging these skills using a standardized manifest format. This guide walks through the exact source files and commands needed to build production-ready skills.

## Generate a Skill Skeleton

The first step to create custom skills for Claude Code is scaffolding the required directory structure. The repository includes **[`skills/skill-creator/scripts/init_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py)**, a helper script that generates a kebab-case folder containing all necessary files.

Run the generator from the repository root:

```bash
python skills/skill-creator/scripts/init_skill.py my-data-cleaner --path skills/public

```

This command performs three critical actions:

1. **Validates the skill name** – Ensures lower-case, hyphenated format with a maximum of 64 characters.
2. **Creates the directory tree** – Generates `scripts/`, `references/`, and `assets/` subdirectories.
3. **Writes the template** – Copies [`template/SKILL.md`](https://github.com/anthropics/skills/blob/main/template/SKILL.md) into the folder with placeholder front-matter.

The `scripts/` folder holds executable Python or Bash helpers, `references/` stores documentation that Claude can load on demand, and `assets/` contains files excluded from context (such as images or templates).

## Configure the SKILL.md Manifest

The **[`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md)** file is the core of every custom skill. Claude Code reads this file to determine when to activate the skill (via front-matter) and what actions to perform (via the markdown body).

### Required Front-Matter

At minimum, the YAML front-matter must include:

```yaml
---
name: my-data-cleaner
description: Clean and normalize CSV data files before analysis. Use when a user says "clean this dataset" or uploads a raw CSV.
---

```

The `name` field must match the directory name exactly. The `description` acts as a trigger prompt—Claude uses semantic matching against this text to decide when to invoke the skill.

### Body Content

The markdown body supports:

- **Workflow documentation** – Step-by-step instructions using H2 and H3 headings.
- **Resource links** – Relative paths to bundled files, such as `[run the cleaning script](scripts/clean_csv.py)` or `[see schema details](references/schema.md)`.
- **Usage examples** – Concrete user queries and expected Claude responses.

Keep the body under approximately 5,000 words (or 500 lines) to remain token-efficient. Claude loads the entire [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) into context when the skill triggers, so concise, structured documentation improves performance.

## Validate Your Skill

Before packaging, run the built-in validator to catch front-matter errors. The **[`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py)** script performs lightweight checks without executing code.

```bash
python skills/skill-creator/scripts/quick_validate.py skills/public/my-data-cleaner

```

The validator verifies:

- Presence of [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md).
- Valid YAML front-matter syntax.
- Allowed front-matter keys (`name`, `description`, `license`, `metadata`, etc.).
- Naming conventions for the `name` field.
- Length limits for `description` and optional `compatibility` fields.

Successful validation outputs `✅ Skill is valid!`. Fix any reported errors before proceeding to packaging.

## Package the Skill

Once validated, bundle your skill into a distributable `.skill` archive using **[`skills/skill-creator/scripts/package_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/package_skill.py)**.

```bash
python skills/skill-creator/scripts/package_skill.py skills/public/my-data-cleaner ./dist

```

This script executes three steps:

1. **Re-validation** – Runs the validator internally; fails immediately if errors exist.
2. **Recursive archiving** – Walks the skill directory, compressing all files into a zip archive while preserving relative paths.
3. **Output generation** – Writes `my-data-cleaner.skill` to the specified output directory.

The resulting `.skill` file is a standard zip archive with the custom extension, containing [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) and all supporting resources.

## Install the Skill in Claude Code

After packaging, install your custom skill into Claude Code using one of two methods:

**Via the Marketplace UI:**

Navigate to Claude Code → *Plugins* → *Marketplace* → *Add local skill*, then select your `my-data-cleaner.skill` file.

**Via command:**

In the Claude Code chat interface, run:

```

/plugin install ./my-data-cleaner.skill

```

Once installed, Claude loads the skill metadata. When a user request semantically matches the `description` field in your [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md), Claude automatically pulls the skill body and any referenced scripts into context to fulfill the request.

## Summary

- **Scaffold** new skills using [`skills/skill-creator/scripts/init_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py), which generates the required folder structure and template [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md).
- **Configure** the skill by editing [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) front-matter (trigger description) and body (workflow documentation), placing helper scripts in `scripts/` and documentation in `references/`.
- **Validate** with [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py) to catch YAML syntax errors and naming violations before packaging.
- **Package** using [`skills/skill-creator/scripts/package_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/package_skill.py) to create a distributable `.skill` archive.
- **Install** via the Claude Code Marketplace UI or the `/plugin install` command to activate the skill for immediate use.

## Frequently Asked Questions

### What programming languages can I use for skill scripts?

You can write executable scripts in any language supported by the target environment, including Python, Bash, or JavaScript. Place these files in the `scripts/` directory and reference them from [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) using relative links. Claude Code will execute these scripts when the skill workflow requires external tool invocation.

### How does Claude Code decide when to activate a custom skill?

Claude Code uses semantic matching against the `description` field in your [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) front-matter. When a user query aligns with the description text—such as "clean this dataset" matching a data cleaning skill description—Claude automatically loads the skill body and any referenced resources into the conversation context to handle the request.

### What is the maximum size for a skill package?

While the repository does not enforce a hard size limit, the [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) body should remain under approximately 5,000 words or 500 lines to ensure token efficiency. The `assets/` folder can contain larger files like images or templates, but these are excluded from Claude's context window unless explicitly referenced, keeping the skill performant.

### Can I distribute skills through the Claude Code Marketplace?

Yes. After packaging your skill with [`package_skill.py`](https://github.com/anthropics/skills/blob/main/package_skill.py), you can distribute the resulting `.skill` file through the Claude Code Marketplace. Users install these skills either via the *Plugins* → *Marketplace* → *Add local skill* UI path or by running the `/plugin install` command with your packaged file path.