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

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 contentsWhat Are Custom Skills in Claude?Skills and custom commands are now the same thingIs Coding Required to Create a Claude Skill?How Claude Skills WorkAnatomy of a Claude SkillThe Frontmatter ReferenceHow a skill gets its command name in Claude CodeWhere Skills LiveHands-On Project: Building a Data Quality AuditorUsing the Skill in Claude CodeUploading 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: FieldPurposenameIdentifier / display name for the skilldescriptionWhat 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. FieldDescriptionnameDisplay 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 → /deploymy-plugin/skills/review/SKILL.mdPlugin-namespaced → /my-plugin:reviewNested 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 toEnterpriseManaged settingsAll users in your organizationPersonal~/.claude/skills//SKILL.mdAll your projectsProject.claude/skills//SKILL.mdThis project onlyPlugin/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 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 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. Free, Pro, Max: turn on “Code execution and file creation” in Settings → Capabilities. Team: enabled by default at the organization level. Skill sharing is off by default. 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 Open Claude. Go to Customize → Skills. Click +, then Create skill. Upload the ZIP. Toggle the skill on. 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) Hi, I am Janvi, a passionate data science enthusiast currently working at Analytics Vidhya. My journey into the world of data began with a deep curiosity about how we can extract meaningful insights from complex datasets.