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

You can create custom skills for Claude Code by generating a skeleton with init_skill.py, editing the SKILL.md manifest, and packaging the result with 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, a helper script that generates a kebab-case folder containing all necessary files.

Run the generator from the repository root:

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

---
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 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 script performs lightweight checks without executing code.

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

The validator verifies:

• Presence of 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.

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 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, 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, which generates the required folder structure and template SKILL.md.
• Configure the skill by editing 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 to catch YAML syntax errors and naming violations before packaging.
• Package using 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 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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}