How to Build and Use Custom Skills in Claude

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.

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:

1. Instructions-only workflow → no code required
2. Deterministic processing or automation → code helps
3. 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:

1. Write guidance that should apply throughout a task as standing instructions, not one-time steps.
2. 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:

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.

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:

1. name and description are both required
2. name: 64 characters maximum
3. description: 200 characters maximum
4. 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

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

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

1. Claude Code installed
2. Python 3.9 or above
3. Pandas (pip install pandas)
4. 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 allowed-tools line. It uses ${CLAUDE_SKILL_DIR} in the permission rule *and* in the command the body tells Claude to run. Because both expand to the same path, the rule matches the exact command, and the script runs without a permission prompt. This is much narrower than a blanket Bash(python3 *), which would pre-approve every Python invocation for that turn.

Step 3: Create the data-quality rules

Create .claude/skills/data-quality-auditor/references/data-quality-rules.md:

Step 4: Create the Python profiling script

Create .claude/skills/data-quality-auditor/scripts/profile_csv.py:

from __future__ import annotations

import argparse
import json
from pathlib import Path
from typing import Any

import pandas as pd

def profile_csv(file_path: Path) -> dict[str, Any]:
    """Generate a structured data-quality profile for a CSV file."""

    if not file_path.exists():
        raise FileNotFoundError(f"File not found: {file_path}")
    if file_path.suffix.lower() != ".csv":
        raise ValueError("The supplied file must have a .csv extension.")

    try:
        dataframe = pd.read_csv(file_path)
    except pd.errors.EmptyDataError as exc:
        raise ValueError("The CSV file is empty.") from exc
    except pd.errors.ParserError as exc:
        raise ValueError(
            "The CSV file could not be parsed. Check its delimiter and structure."
        ) from exc

    row_count = len(dataframe)
    column_count = len(dataframe.columns)

    missing_count = dataframe.isna().sum()
    missing_percentage = (
        dataframe.isna().mean().mul(100).round(2)
        if row_count > 0
        else pd.Series(0.0, index=dataframe.columns)
    )

    missing_values = {
        column: {
            "count": int(missing_count[column]),
            "percentage": float(missing_percentage[column]),
        }
        for column in dataframe.columns
        if missing_count[column] > 0
    }

    duplicate_count = int(dataframe.duplicated().sum())
    duplicate_percentage = (
        round((duplicate_count / row_count) * 100, 2) if row_count > 0 else 0.0
    )

    data_types = {
        column: str(dtype) for column, dtype in dataframe.dtypes.items()
    }

    unique_counts = {
        column: int(dataframe[column].nunique(dropna=True))
        for column in dataframe.columns
    }

    # A constant column has exactly one distinct non-null value.
    # A column with zero distinct values is empty, which is a different problem.
    constant_columns = [
        column for column, count in unique_counts.items() if count == 1
    ]
    empty_columns = [
        column for column, count in unique_counts.items() if count == 0
    ]

    numeric_columns = set(dataframe.select_dtypes(include="number").columns)

    high_cardinality_columns = []
    possible_encoded_identifiers = []

    for column in dataframe.columns:
        non_null_count = int(dataframe[column].notna().sum())
        if non_null_count == 0:
            continue

        uniqueness_ratio = unique_counts[column] / non_null_count
        if uniqueness_ratio < 0.80:
            continue

        entry = {
            "column": column,
            "unique_values": unique_counts[column],
            "uniqueness_percentage": round(uniqueness_ratio * 100, 2),
        }

        # The rules file treats near-unique numeric columns as possible
        # identifiers rather than high-cardinality categoricals.
        if column in numeric_columns:
            possible_encoded_identifiers.append(entry)
        else:
            high_cardinality_columns.append(entry)

    numeric_dataframe = dataframe.select_dtypes(include="number")
    numeric_summary: dict[str, Any] = (
        {}
        if numeric_dataframe.empty
        else json.loads(numeric_dataframe.describe().round(3).to_json())
    )

    return {
        "file": str(file_path),
        "rows": row_count,
        "columns": column_count,
        "duplicate_rows": duplicate_count,
        "duplicate_percentage": duplicate_percentage,
        "data_types": data_types,
        "missing_values": missing_values,
        "unique_value_counts": unique_counts,
        "constant_columns": constant_columns,
        "empty_columns": empty_columns,
        "high_cardinality_columns": high_cardinality_columns,
        "possible_encoded_identifiers": possible_encoded_identifiers,
        "numeric_summary": numeric_summary,
    }


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Profile a CSV file for common data-quality issues."
    )
    parser.add_argument("file_path", type=Path, help="Path to the CSV file")
    arguments = parser.parse_args()

    try:
        profile = profile_csv(arguments.file_path)
        print(json.dumps(profile, indent=2))
    except (FileNotFoundError, ValueError) as exc:
        print(json.dumps({"success": False, "error": str(exc)}, indent=2))
        raise SystemExit(1) from exc


if __name__ == "__main__":
    main()

What the script does

The script performs the deterministic work: validating the file, loading it with Pandas, counting rows and columns, calculating missing-value percentages, detecting duplicates, extracting data types, finding constant and empty columns, separating high-cardinality categoricals from near-unique numeric columns, generating descriptive statistics, and returning everything as JSON.

Note how the script and the rules file agree. Earlier versions of this kind of skill often flag every near-unique column as “high cardinality,” including integer primary keys, and then contradict a rules file that says the check applies to text columns. When the deterministic layer and the interpretive layer disagree, Claude produces confusing reports. Keep them aligned.

The division of responsibility is the point:

Python handles deterministic calculations. Claude handles interpretation and recommendations.

Step 5: Test the script directly

python3 .claude/skills/data-quality-auditor/scripts/profile_csv.py data/customers.csv

Example output:

Resolve script errors before testing the skill through Claude Code.

Using the Skill in Claude Code

Start Claude Code inside the project:

claude

Invoke it directly:

/data-quality-auditor data/customers.csv

Or use natural language and let Claude decide:

Audit data/customers.csv and tell me whether it is ready for machine learning.

You can also stack skills at the start of a message. Typing /write-tests /fix-issue 123 loads both skills and passes 123 as the arguments to each. Expansion stops at the first token that is not an inline user-invocable skill.

Uploading the Skill to Claude (Web and Desktop)

You can also package the skill and upload it to claude.ai.

Enable the prerequisites

Skills require code execution.

1. Free, Pro, Max: turn on “Code execution and file creation” in Settings → Capabilities.
2. Team: enabled by default at the organization level. Skill sharing is off by default.
3. Enterprise: an Owner must enable both “Code execution and file creation” and Skills in Organization settings → Skills. Owners can also provision skills organization-wide, which then appear automatically for all users.

Package the skill

The ZIP must contain the skill folder as its root not the loose files, and not a wrapper directory.

Correct:

Incorrect: files sitting directly in the ZIP root.

Make sure the folder name matches the skill’s name.

Upload

1. Open Claude.
2. Go to Customize → Skills.
3. Click +, then Create skill.
4. Upload the ZIP.
5. Toggle the skill on.
6. Test it with a relevant prompt.

Skills you upload are private to your individual account unless an Owner provisions them organization-wide.

Iterating in the app

When you work on a skill with Claude in chat, the skill files open beside the conversation. Highlight the text you want changed, click Edit with Claude, and describe the change. For multi-file skills you can leave requests across several files and send them together, and Claude applies them in one pass.

Recording a skill instead of writing one

On Pro, Max, and Team plans, in Cowork in Claude for Mac, you can record yourself performing a task and let Claude build the skill from the recording. Start it from the + button in the composer or from Customize → Skills → Add → Record your screen. Narrate as you work the commentary gives Claude context the screen alone does not.

Recordings run about ten minutes. Do not display passwords, secrets, or private conversations while recording; everything on screen is captured. The video and audio are not retained, but a set of screenshots is saved in the Cowork task.

This is not available in chat, on Windows, or on Free and Enterprise plans.

Conclusion

Custom Skills turn Claude from a general assistant into a system that follows your specific workflows.

A skill can be as simple as one Markdown file. No programming is required for basic workflows. For more advanced cases, it can bundle Python scripts, shell scripts, JavaScript utilities, templates, reference documents, validation logic, and example outputs.

The most effective approach is to start with one focused workflow audit a CSV dataset then write a clear description, define the workflow, specify the output format, test both relevant and irrelevant prompts, add code only where deterministic execution is required, and improve the skill based on actual failures rather than imagined ones.

The goal is not to store everything you know inside one skill. The goal is to capture one repeatable process and make it reliable.

Read more: How to Connect MCP Servers with Claude (Claude Desktop and Claude Code)