How to Create Custom Skills in Claude: A Step-by-Step Guide

-->

How to Build and Use Custom Skills in Claude

India's Most Futuristic AI Conference Is Back – Bigger, Sharper, Bolder

d

:

h

:

m

:

s

Career

GenAI

Prompt Engg

ChatGPT

LLM

Langchain

RAG

AI Agents

Machine Learning

Deep Learning

GenAI Tools

LLMOps

Python

NLP

SQL

AIML Projects

Reading list

How to Become a Data Analyst in 2025: A Complete RoadMap

A Comprehensive Learning Path to Tableau in 2025

A Comprehensive NLP Learning Path 2025

Learning Path to Become a Data Scientist in 2025

Step-by-Step Roadmap to Become a Data Engineer in 2025

A Comprehensive MLOps Learning Path: 2025 Edition

Roadmap to Become an AI Engineer in 2025

A Comprehensive Learning Path to Master Computer Vision in 2025

Best Roadmap to Learn Generative AI in 2025

GenAI Roadmap for Enterprises

Large Language Models Demystified: A Beginner’s Roadmap

Learning Path to Become a Prompt Engineering Specialist

How to Create Custom Skills in Claude: A Step-by-Step Guide

Janvi Kumari Last Updated : 29 Jul, 2026

11 min read

Claude can review data, check code, write reports, and prepare presentations, but teams still end up repeating the same structure, validation rules, company standards, and final-check instructions in every conversation. That repetition wastes time and often leads to inconsistent results.

Custom Skills solve this by packaging reusable instructions, workflows, templates, scripts, examples, and reference files that Claude automatically loads for matching tasks. In this article, we’ll explore how Claude Skills works, examine the configuration options, and build a practical CSV auditing skill step by step.

Table of contents

What Are Custom Skills in Claude?

Skills and custom commands are now the same thing

Is Coding Required to Create a Claude Skill?

How Claude Skills Work

Anatomy of a Claude Skill

The Frontmatter Reference

How a skill gets its command name in Claude Code

Where Skills Live

Hands-On Project: Building a Data Quality Auditor

Using the Skill in Claude Code

Uploading the Skill to Claude (Web and Desktop)

Conclusion

What Are Custom Skills in Claude?

A skill is a directory. It contains instructions for Claude, and optionally extra resources that help Claude complete a specific task.

Every skill needs one file:

SKILL.md

This file defines what the skill does, when it should be used, and the steps Claude should follow. It can define the output format and point to scripts, templates, examples, or reference files.

A more advanced skill may look like this:

Only SKILL.md is required. Everything else is optional.

Skills follow the Agent Skills open standard agentskills.io, which means the portable core: name, description, and plain Markdown works across Claude apps, Claude Code, the Claude Agent SDK, and the Claude Developer Platform. Individual products then extend the standard with their own features, and this is where most confusion comes from. We will map those differences carefully later in the article.

Skills and custom commands are now the same thing

If you have used Claude Code before, you probably have files sitting in .claude/commands/. Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way.

Your existing command files keep working. Skills simply add optional capabilities on top: a directory for supporting files, frontmatter that controls whether you or Claude invokes them, and automatic loading when the task is relevant.

If a skill and a command share the same name, the skill takes precedence.

Is Coding Required to Create a Claude Skill?

No. A basic custom skill needs nothing but Markdown.

For example:

That is already complete, working skill.

When is code useful then?

Code becomes useful when your skill needs to analyse data, process files, validate outputs, generate visualisations, transform structured information, call command-line utilities, perform deterministic calculations, create or modify documents, or automate development workflows.

A simple rule:

Instructions-only workflow → no code required

Deterministic processing or automation → code helps

External system integration → usually needs tools, scripts, or MCP

Start with Markdown. Add code only when instructions alone cannot produce reliable execution.

How Claude Skills Work

Skills use progressive disclosure. Instead of loading every skill and every file into the context window, Claude loads information in stages.

Stage 1: Discovery

At startup, Claude reads only the metadata from each available skill essentially the name and description:

Claude uses the description to decide whether the skill matches your request.

This should activate the skill:

Can you check this customer dataset for data quality problems?

This should not:

Write an email announcing the product launch.

The description is the single most important field in the file, because it is the only thing Claude sees before deciding whether to load anything else.

Stage 2: Instruction loading

Once Claude decides the skill is relevant, it loads the Markdown body of SKILL.md. This is where the workflow, rules, constraints, validation checks, and output format live.

Stage 3: Supporting resources

Claude then reads scripts, examples, references, and templates only as needed:

Reference files and data cost no context tokens until they are actually read. Scripts cost even less: they execute through bash, and only their output consumes context.

One important consequence: skill content persists

When a skill is invoked in Claude Code, the rendered SKILL.md enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the file on later turns.

Two practical implications:

Write guidance that should apply throughout a task as standing instructions, not one-time steps.

Every line in SKILL.md is a recurring token cost. Keep the body lean and push detail into reference files.

During auto-compaction, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each within a combined 25,000-token budget. The skills you invoked long ago can be dropped entirely. If a skill seems to stop influencing behaviour after a long session, re-invoke it.

Anatomy of a Claude Skill

A typical skill directory:

SKILL.md is the entry point: YAML frontmatter between markers, followed by Markdown instructions.

references/ holds detailed information Claude may need coding standards, business rules, validation checklists.

examples/ shows what a good and a bad result looks like.

templates/ provides a fixed output structure.

scripts/ performs deterministic processing.

Bundling a file is not enough on its own. Reference it explicitly from SKILL.md so Claude knows what it contains and when to open it:

Keep SKILL.md under about 500 lines.

The Frontmatter Reference

This is where the products diverge, so it is worth being precise.

The portable core

These two fields work everywhere:

FieldPurpose

nameIdentifier / display name for the skill

descriptionWhat the skill does and when to use it

Claude Code

In Claude Code, all frontmatter fields are optional. Only description is recommended, and if you omit it, Claude Code falls back to the first paragraph of the Markdown body. name defaults to the directory name.

FieldDescription

nameDisplay name in skill listings. Defaults to the directory name.

descriptionWhat does the skill do and when to use it. Claude matches against this.

when_to_useExtra trigger phrases or example requests, appended to the description.

argument-hintAutocomplete hint, e.g. [csv-file-path].

argumentsNamed positional arguments for $name substitution.

disable-model-invocationtrue prevents Claude from loading the skill automatically.

user-invocablefalse hides the skill from the / menu.

allowed-toolsTools Claude may use without a permission prompt during the invoking turn.

disallowed-toolsTools removed from Claude’s pool while the skill is active.

modelModel to use while the skill is active.

effortEffort level: low, medium, high, xhigh, max.

contextSet to fork to run in a subagent context.

agentWhich subagent type to use with context: fork.

backgroundWith context: fork, false waits for the result in the invoking turn.

hooksHooks scoped to this skill’s lifecycle.

pathsGlob patterns limiting when the skill auto-activates.

shellbash (default) or powershell for inline shell commands.

Two of these deserve more attention than they usually get.

when_to_use is where trigger phrases belong. Putting them in description bloats the field; when_to_use keeps the primary description clean while still feeding the matcher.

paths limits automatic activation to files matching a glob. A skill for React conventions that only activates when Claude touches src/**/*.tsx will not fire during a database migration.

Claude.ai (uploaded skills)

The web and desktop app is stricter, and this trips people up:

name and description are both required

name: 64 characters maximum

description: 200 characters maximum

dependencies is an optional field for required packages, e.g. python>=3.8, pandas>=1.5.0

That 200-character description limit is a real constraint. Write it as one tight sentence covering what the skill does and when it applies.

How a skill gets its command name in Claude Code

LocationCommand name comes from

~/.claude/skills/deploy-staging/SKILL.mdDirectory name → /deploy-staging

.claude/commands/deploy.mdFile name → /deploy

my-plugin/skills/review/SKILL.mdPlugin-namespaced → /my-plugin:review

Nested skill with a name clashDirectory-qualified → /apps/web:deploy

For personal and project skills, the frontmatter name sets only on the display label. The command still comes from the directory name. For plugin skills, the name replaces the last segment of the command.

Where Skills Live

LocationPathApplies to

EnterpriseManaged settingsAll users in your organization

Personal~/.claude/skills//SKILL.mdAll your projects

Project.claude/skills//SKILL.mdThis project only

Plugin/skills//SKILL.mdWherever the plugin is enabled

When names collide, enterprise overrides personal, and personal overrides project. A skill at any of these levels also overrides a bundled skill of the same name so a code-review skill in your project replaces the built-in /code-review.

Three behaviours worth knowing:

Parent and nested discovery: Project skills load from .claude/skills/ in your starting directory and in every parent directory up to the repository root. When Claude works on files in a subdirectory, skills from that subdirectory’s .claude/skills/ also become available. This is what makes monorepo package-level skills work.

Live change detection: Editing a skill takes effect within the current session without restarting. Creating a brand-new top-level skills directory does require a restart.

Cowork and cloud sessions do not read your local ~/.claude/skills/: They load the skills enabled for your claude.ai account instead. If a scheduled routine reports that a skill was not found, this is usually why. Enable the skill for your account or commit it to the repository’s .claude/skills/.

Hands-On Project: Building a Data Quality Auditor

We will build a skill that analyses CSV datasets and checks row and column counts, missing values, duplicate records, column data types, high-cardinality columns, constant columns, numeric summaries, and other suspicious patterns.

Prerequisites

Claude Code installed

Python 3.9 or above

Pandas (pip install pandas)

A project directory and a CSV file for testing

Step 1: Create the skill directory

For a project-level skill:

Resulting structure:

For personal skills available across all projects, use ~/.claude/skills/ instead.

Step 2: Create SKILL.md

Create .claude/skills/data-quality-auditor/SKILL.md:

Notice the allow

[truncated for AI cost control]