Claude Skills: Build Reusable AI Instructions That Load Only When Needed

Every Claude conversation starts the same way. You paste instructions. You explain context. You describe the output format you want. The next conversation, you do it all again. Custom instructions help, but they load for every conversation whether relevant or not.

Claude Skills solve this problem with progressive disclosure. Skills are bundled instructions that Claude accesses only when needed. The metadata loads at startup (around 100 tokens). The full instructions load only when relevant (up to 5,000 tokens). Additional files load on demand (unlimited). You write instructions once. Claude decides when to use them.

TL;DR

Claude Skills are reusable instruction packages stored as markdown files in a specific folder structure. Claude reads skill metadata at startup, then loads full instructions only when relevant to the conversation. Skills support additional files, folders, and Python/JavaScript tools that Claude accesses progressively. This approach saves context window space while giving Claude access to hundreds of specialized capabilities. Marketing teams build skills for campaign analysis, content creation, competitor research, and any repeatable workflow.

Key Takeaways

Skills are markdown files with metadata and instructions that Claude loads on demand
Progressive disclosure means Claude gets just enough context for the next step
Skill metadata uses about 100 tokens while full instructions can be 5,000 tokens
Additional files and folders within a skill have no practical token limit
Skills can include Python and JavaScript tools Claude executes in its environment
Skills differ from MCP by offering progressive loading versus upfront context dumps
Marketing teams build skills for any repeatable analysis, creation, or research workflow

What Are Claude Skills and How Do They Work?

Claude Skills are reusable instructions Claude accesses when relevant to a conversation. A skill is a folder containing a SKILL.md file with metadata and instructions. Claude reads the metadata at startup and loads full instructions only when the skill applies to your request.

The clearer your instructions, the better your results. Skills let you write detailed instructions once and reuse them forever. Claude decides when each skill applies based on the conversation context.

What Is the Structure of a Claude Skill?

A Claude Skill consists of a folder with a SKILL.md file inside. The folder name becomes the skill identifier. The SKILL.md file contains two parts: metadata and body.

The metadata includes the skill name (64 character limit) and description (1,024 character limit). The body contains the full instructions in markdown format. This body can be up to 5,000 tokens of detailed guidance.

Basic folder structure for a skill:

skills/
└── campaign-analyzer/
    └── SKILL.md

What Is Progressive Disclosure?

Progressive disclosure means Claude gets just enough context for the next step. Instead of loading all instructions at conversation start, content enters the context window only when needed.

Three levels of progressive disclosure exist in Claude Skills:

Level 1 - Metadata: Name and description load at startup (about 100 tokens)
Level 2 - Body: Full instructions load when skill is invoked (up to 5,000 tokens)
Level 3 - Additional Files: Referenced files load on demand (unlimited)

This architecture lets you have hundreds of skills without overwhelming the context window. Claude selects and loads only what applies to the current conversation.

Why Does Progressive Disclosure Matter for Marketing?

Marketing teams run diverse workflows. Campaign analysis, content creation, competitor research, and reporting all require different instructions. Loading all instructions for every conversation wastes tokens and dilutes Claude’s attention.

With progressive disclosure, you build a skill for each workflow. Claude loads the campaign analyzer skill when you ask about performance. Claude loads the content creator skill when you request blog posts. Each conversation gets focused instructions without the noise of irrelevant capabilities.

Action item: List five recurring workflows where you give Claude the same instructions repeatedly. These are candidates for your first skills.

How Do You Create Your First Claude Skill?

Creating a skill requires a folder with a SKILL.md file in the correct location. Claude Code users place skills in ~/.claude/skills/. Claude Desktop and web users upload skills to Projects. The structure stays consistent across platforms.

Step 1: Create the Skill Folder

Create a folder with a descriptive name for your skill. Use lowercase with hyphens for folder names. The folder name helps you organize but does not affect how Claude identifies the skill.

mkdir -p ~/.claude/skills/marketing-analyst

Step 2: Create the SKILL.md File

The SKILL.md file contains metadata at the top and instructions below. Metadata uses a specific format that Claude parses automatically.

SKILL.md Structure:

The file starts with YAML frontmatter containing name and description, followed by the instruction body in markdown format.

Metadata Section (between --- markers):

name: Marketing Analyst
description: Use when user asks for campaign analysis, performance metrics, or marketing data interpretation. Analyzes data, calculates KPIs, and provides actionable insights.

Body Section (after second --- marker):

The body contains your full instructions organized with headers:

Role: Define who Claude should be (e.g., senior marketing analyst)
When to Use This Skill: List trigger conditions
Analysis Framework: Numbered steps for the workflow
Output Format: Template for responses
Calculation Standards: Rules for consistency

Here is a complete SKILL.md example you can copy:

---
name: Marketing Analyst
description: Use when user asks for campaign analysis, performance metrics, or marketing data interpretation. Analyzes data, calculates KPIs, and provides actionable insights.
---

Then add the body content as regular markdown (not inside a code block):

# Marketing Analyst Skill

## Role

You are a senior marketing analyst with expertise in campaign performance, attribution modeling, and data-driven optimization.

## When to Use This Skill

User asks about campaign performance
User requests marketing metrics or KPIs
User needs data analysis or interpretation
User wants optimization recommendations

## Analysis Framework

When analyzing marketing data:

Identify the business question being asked
Determine which metrics answer that question
Calculate relevant KPIs (CTR, CVR, CPA, ROAS, LTV)
Compare against benchmarks or historical data
Provide specific, actionable recommendations

## Output Format

Structure all analysis responses with:

Summary: One sentence answer to the question
Key Metrics: Table of relevant numbers
Insights: 3-5 observations from the data
Recommendations: Specific next steps with expected impact

## Calculation Standards

Round percentages to 2 decimal places
Format currency with appropriate symbols
Use NULLIF to prevent division by zero errors
Always show sample size for statistical context

Step 3: Test Your Skill

Open Claude Code or start a new conversation in a Claude Project with your skill uploaded. Ask a question that should trigger the skill.

Test with: “Analyze this campaign data and tell me which channel performs best.”

Claude should invoke the Marketing Analyst skill automatically based on the request type.

Action item: Create your first skill using the template above. Test it with three different requests to verify Claude invokes it correctly.

How Do You Add Additional Files to a Skill?

Skills support multiple files beyond the main SKILL.md. Additional files provide specialized instructions, reference documentation, or templates that Claude loads on demand. Reference these files in your main skill body.

When to Use Additional Files

Add additional files when:

Instructions exceed 5,000 tokens and need splitting
Some instructions apply only in specific situations
You have reference documentation Claude should access
You want different instruction sets for different sub-tasks

File Structure with Additional Files

skills/
└── marketing-analyst/
    ├── SKILL.md
    ├── cohort-analysis.md
    ├── attribution-models.md
    └── benchmark-data.md

Referencing Additional Files

Reference additional files in your SKILL.md body. Claude reads these files only when the reference triggers based on conversation context.

Add this section to your SKILL.md body:

## Specialized Analysis Types

### Cohort Analysis

If the user asks about retention, cohorts, or user lifecycle, load cohort-analysis.md for detailed methodology.

### Attribution Analysis

If the user asks about attribution, channel credit, or conversion paths, load attribution-models.md for model specifications.

### Benchmark Comparison

If the user asks how metrics compare to industry standards, load benchmark-data.md for reference benchmarks.

Example Additional File: cohort-analysis.md

Create a separate file called cohort-analysis.md with specialized instructions:

# Cohort Analysis Methodology

## When to Use

Apply this methodology when analyzing:

User retention over time
Cohort-based LTV calculations
Signup cohort performance comparison
Feature adoption by cohort

## Cohort Definition

A cohort is a group of users who share a common characteristic within a defined time period. The most common cohort types:

Acquisition Cohort: Users who signed up in the same week/month
Behavioral Cohort: Users who completed a specific action
Channel Cohort: Users acquired through the same marketing channel

## Retention Calculation

Calculate retention as: (Users active in period N) / (Cohort size at period 0) * 100

Period 0 is always 100% by definition. Track periods 1 through 12 for meaningful patterns.

## Output Format

Present cohort data as a matrix:

Rows: Cohort periods (signup week/month)
Columns: Retention periods (week 0, week 1, etc.)
Cells: Retention percentage or absolute users

## Red Flags to Identify

Retention dropping below 20% by period 4
Large variance between similar cohorts
Sudden drops indicating product or marketing issues

Action item: Identify which parts of your skill instructions apply only in specific situations. Extract those into separate files and add conditional references in your main SKILL.md.

How Do You Add Custom Tools to a Skill?

Claude runs in an environment with bash, Python, and Node.js. Skills can include scripts that Claude executes to perform specific functions. Tools extend what Claude can do beyond text generation.

When to Add Custom Tools

Add custom tools when:

You need to fetch external data (APIs, web pages, files)
You want Claude to perform calculations programmatically
You need consistent data transformations
You want to integrate with external services

Tool Structure

Create a scripts folder within your skill folder. Add Python or JavaScript files that Claude can execute.

skills/
└── marketing-analyst/
    ├── SKILL.md
    ├── cohort-analysis.md
    └── scripts/
        ├── calculate_ltv.py
        └── fetch_benchmark.py

Example Python Tool: calculate_ltv.py

#!/usr/bin/env python3
"""
Calculate Customer Lifetime Value from cohort data.
Usage: python calculate_ltv.py --arpu 50 --retention 0.85 --months 24
"""

import argparse

def calculate_ltv(arpu: float, monthly_retention: float, months: int) -> dict:
    """
    Calculate LTV using retention-based model.
    
    Args:
        arpu: Average Revenue Per User per month
        monthly_retention: Monthly retention rate (0-1)
        months: Number of months to project
    
    Returns:
        Dictionary with LTV calculation details
    """
    cumulative_revenue = 0
    retained_users = 1.0
    monthly_breakdown = []
    
    for month in range(1, months + 1):
        if month > 1:
            retained_users *= monthly_retention
        month_revenue = arpu * retained_users
        cumulative_revenue += month_revenue
        monthly_breakdown.append({
            "month": month,
            "retained_pct": round(retained_users * 100, 2),
            "revenue": round(month_revenue, 2),
            "cumulative": round(cumulative_revenue, 2)
        })
    
    return {
        "ltv": round(cumulative_revenue, 2),
        "arpu": arpu,
        "retention_rate": monthly_retention,
        "projection_months": months,
        "monthly_breakdown": monthly_breakdown
    }

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Calculate Customer LTV")
    parser.add_argument("--arpu", type=float, required=True, help="Average Revenue Per User")
    parser.add_argument("--retention", type=float, required=True, help="Monthly retention rate")
    parser.add_argument("--months", type=int, default=24, help="Months to project")
    
    args = parser.parse_args()
    result = calculate_ltv(args.arpu, args.retention, args.months)
    
    print(f"LTV: ${result['ltv']}")
    print(f"Based on: ${args.arpu} ARPU, {args.retention*100}% monthly retention, {args.months} months")

Referencing Tools in SKILL.md

Add a Custom Tools section to your SKILL.md that tells Claude how to use the script:

## Custom Tools

### LTV Calculator

To calculate customer lifetime value programmatically, run:

python scripts/calculate_ltv.py --arpu {{ARPU}} --retention {{RETENTION_RATE}} --months {{MONTHS}}

Parameters:

—arpu: Average monthly revenue per user in dollars
—retention: Monthly retention rate as decimal (e.g., 0.85 for 85%)
—months: Number of months to project (default: 24)

Use this tool when:

User asks for LTV calculation
User provides ARPU and retention data
User wants to project customer value over time

Action item: Identify one calculation or data fetch you perform repeatedly. Write a Python script that automates it. Add the script to a skill folder and reference it in your SKILL.md.

How Do Skills Differ from MCP?

Skills and MCP (Model Context Protocol) both give Claude additional capabilities. They overlap functionally but differ in implementation and use cases. Understanding the differences helps you choose the right approach.

Key Differences

Aspect	Skills	MCP
Platform	Claude only	Universal standard
Context loading	Progressive (on demand)	Upfront (all at once)
Metadata cost	~100 tokens	~20,000+ tokens for complex servers
Primary use	Teaching Claude workflows	Complex integrations
Setup complexity	Markdown files	Server implementation

When to Use Skills

Use skills when teaching Claude how to do things with available tools. Skills excel at:

Workflow instructions and methodology
Analysis frameworks and output formats
Research processes and validation steps
Content creation guidelines and templates

When to Use MCP

Use MCP when giving Claude access to complex external integrations. MCP excels at:

Database connections (Snowflake, PostgreSQL)
Application integrations (Notion, Slack, Google Drive)
API access requiring authentication
Real-time data fetching from external services

Using Skills and MCP Together

Skills and MCP work together effectively. Use MCP for the data connection. Use skills for the analysis methodology.

Example: Connect Snowflake via MCP. Create a skill that teaches Claude your specific analysis patterns, metric definitions, and output formats. Claude uses MCP to fetch data and the skill to analyze it correctly.

Action item: Review your current MCP connections. Create skills that define how Claude should use each connection for your specific workflows.

What Skills Should Marketing Teams Build First?

Marketing teams benefit from skills covering recurring analysis, content creation, and research workflows. Start with high-frequency tasks where consistent methodology matters.

Skill 1: Campaign Performance Analyzer

Build a skill that standardizes how Claude analyzes campaign data. Use this prompt to generate the skill:

SYSTEM: You are a skill architect who creates Claude Skills for marketing teams.

<context>
Skill purpose: Analyze marketing campaign performance
Data sources: CSV uploads, connected databases
Key metrics: CTR, CVR, CPA, ROAS, LTV
Output needs: Executive summaries, detailed breakdowns, recommendations
</context>

Create a complete SKILL.md file for a Campaign Performance Analyzer.

MUST include:
1. Metadata with name and description under character limits
2. Role definition for the analyst persona
3. When to use triggers (what requests invoke this skill)
4. Analysis framework with numbered steps
5. Metric calculation standards with formulas
6. Output format templates for different report types
7. Benchmark references for comparison
8. Common pitfalls to avoid in analysis

Output: Complete SKILL.md file ready to save.

Skill 2: Content Brief Generator

Build a skill that creates consistent content briefs:

SYSTEM: You are a skill architect who creates Claude Skills for content marketing.

<context>
Skill purpose: Generate comprehensive content briefs
Content types: Blog posts, landing pages, email sequences
Requirements: SEO keywords, audience targeting, competitive context
Output needs: Structured brief with all sections a writer needs
</context>

Create a complete SKILL.md file for a Content Brief Generator.

MUST include:
1. Metadata with name and description
2. Brief structure template with all required sections
3. Keyword research methodology
4. Audience analysis framework
5. Competitive content review process
6. SEO requirements checklist
7. Output format for the complete brief

Output: Complete SKILL.md file ready to save.

Skill 3: Competitor Research Analyst

Build a skill that standardizes competitive analysis:

SYSTEM: You are a skill architect who creates Claude Skills for competitive intelligence.

<context>
Skill purpose: Research and analyze competitors
Research sources: Websites, social media, review sites, job postings
Analysis areas: Positioning, pricing, features, messaging, audience
Output needs: Structured competitive profiles and comparison matrices
</context>

Create a complete SKILL.md file for a Competitor Research Analyst.

MUST include:
1. Metadata with name and description
2. Research methodology with source priorities
3. Analysis framework for each competitor dimension
4. Comparison matrix template
5. Insight extraction guidelines
6. Recommendation generation process
7. Reference to web search tool usage

Output: Complete SKILL.md file ready to save.

Skill 4: SQL Query Generator

Build a skill that generates marketing analytics queries:

SYSTEM: You are a skill architect who creates Claude Skills for marketing analytics.

<context>
Skill purpose: Generate SQL queries for marketing analysis
Database types: Snowflake, BigQuery, PostgreSQL
Common analyses: Campaign metrics, cohorts, attribution, funnels
Output needs: Executable SQL with documentation
</context>

Create a complete SKILL.md file for a SQL Query Generator.

MUST include:
1. Metadata with name and description
2. Schema documentation template
3. Query patterns for common marketing analyses
4. Parameter substitution standards
5. SQL style guide (formatting, naming conventions)
6. Output format with query and explanation
7. Testing and validation steps

Output: Complete SKILL.md file ready to save.

Action item: Generate all four skills using the prompts above. Save each to your skills folder. Test each skill with real requests from your marketing workflow.

How Do You Organize Multiple Skills?

As your skill library grows, organization becomes important. Structure your skills folder for easy maintenance and logical grouping.

Recommended Folder Structure

~/.claude/skills/
├── analysis/
│   ├── campaign-analyzer/
│   │   ├── SKILL.md
│   │   ├── cohort-analysis.md
│   │   └── scripts/
│   │       └── calculate_ltv.py
│   ├── funnel-analyzer/
│   │   └── SKILL.md
│   └── attribution-modeler/
│       └── SKILL.md
├── content/
│   ├── blog-writer/
│   │   ├── SKILL.md
│   │   └── style-guide.md
│   ├── email-creator/
│   │   └── SKILL.md
│   └── brief-generator/
│       └── SKILL.md
├── research/
│   ├── competitor-analyst/
│   │   └── SKILL.md
│   └── market-researcher/
│       └── SKILL.md
└── operations/
    ├── sql-generator/
    │   ├── SKILL.md
    │   └── query-templates/
    │       ├── campaign-queries.md
    │       └── cohort-queries.md
    └── report-builder/
        └── SKILL.md

Naming Conventions

Follow consistent naming for maintainability:

Folder names: lowercase with hyphens (campaign-analyzer)
Skill files: always SKILL.md (required)
Additional files: descriptive lowercase with hyphens (cohort-analysis.md)
Script files: descriptive with appropriate extension (calculate_ltv.py)

Version Control for Skills

Store your skills folder in Git for version history and team sharing:

cd ~/.claude/skills
git init
git add .
git commit -m "Initial skill library with marketing analysis skills"

Share skills across your team by pushing to a shared repository. Team members clone the repository to their skills folder.

Action item: Organize your existing skills into a logical folder structure. Initialize Git version control. Commit your current skills as the baseline.

How Do You Iterate and Improve Skills?

Skills improve through usage feedback. Track which skills work well, which need refinement, and which gaps exist in your library.

Track Skill Performance

Create a simple log to track skill effectiveness:

Date	Request	Skill Used	Outcome	Improvement Needed
2024-12-30	Campaign analysis Q4	campaign-analyzer	Success	None
2024-12-30	Email subject lines	blog-writer	Partial	Add email-specific skill
2024-12-30	SQL for cohorts	sql-generator	Success	None

Common Improvements

Skills typically need these refinements after initial use:

More specific triggers: Add phrases that should invoke the skill
Better output formats: Refine templates based on actual needs
Additional examples: Show Claude more ways to apply the instructions
Edge case handling: Document what to do in unusual situations

Use Claude to Improve Skills

Ask Claude to help refine skills based on conversation outcomes:

SYSTEM: You are a skill improvement specialist.

<context>
Current skill: {{PASTE_CURRENT_SKILL_MD}}
Recent request: {{WHAT_USER_ASKED}}
Actual output: {{WHAT_CLAUDE_PRODUCED}}
Desired output: {{WHAT_YOU_WANTED}}
</context>

Analyze why the skill produced suboptimal output. Suggest specific improvements to the SKILL.md file.

MUST provide:
1. Diagnosis of what went wrong
2. Specific text changes to the skill file
3. New examples to add for clarity
4. Any additional files that would help

Output: Updated SKILL.md file with improvements highlighted.

Action item: After using each skill five times, review the outcomes. Identify one improvement per skill and implement it. Commit the changes to version control.

Final Takeaways

Claude Skills transform one-time instructions into permanent, reusable capabilities. Write detailed instructions once, and Claude applies them whenever relevant.

Progressive disclosure keeps your context window clean. Hundreds of skills add minimal overhead because only metadata loads at startup. Full instructions load on demand.

Skills and MCP serve different purposes. Use skills for methodology and workflow instructions. Use MCP for complex external integrations. Combine both for powerful, well-documented capabilities.

Start with your highest-frequency workflows. Campaign analysis, content creation, and competitor research make excellent first skills. Each skill you build saves time on every future request.

Version control your skills and iterate based on usage. Track what works, refine what does not, and fill gaps as you discover them. Your skill library compounds in value with every addition.