Packaging Visualization Expertise into Agent Skills

In the previous lesson, you learned to package prompts into slash commands that you trigger explicitly by typing /command-name. But what if Claude could recognize when a capability is needed and apply it automatically? Imagine describing a visualization problem in plain English, and Claude realizes on its own that it should follow your chart styling guidelines, reference your style guide, and use your template scripts — all without you invoking a specific command.

This is exactly what Agent Skills provide. Skills are modular capability packages that Claude triggers automatically based on the context of your request. For complex visualization workflows with detailed processes for styling, templates, or layout conventions, Skills let Claude access deep capabilities only when relevant — keeping your context lean while enabling powerful, specialized behavior.

Skills live in dedicated directories that Claude scans when starting a session. There are two locations where you can place them:

For visualization workflows tied to a specific dataset and style guide — like your penguin analysis project — project-level Skills in .claude/skills/ are typically what you want. Personal Skills are useful for general-purpose capabilities you use everywhere, such as code review patterns or documentation standards.

When you start a Claude Code session, Claude discovers all available Skills by scanning these directories. Each Skill includes a description that tells Claude the types of requests it applies to. When you ask a question or describe a task, Claude evaluates the intent of your request against these descriptions. This is not a simple keyword match; Claude uses its semantic understanding to determine if the underlying goal of your query aligns with the Skill's purpose. If there is a match, Claude loads that Skill's instructions and resources.

The key distinction from slash commands is this: you do not type /skill-name to activate a Skill. Claude decides to use it based on what you are asking. This means Skills work silently in the background, bringing domain expertise into the conversation exactly when it is needed.

A Skill is a folder inside .claude/skills/ (or ~/.claude/skills/ for personal Skills). The folder name becomes the Skill's identifier. Here is the minimal structure:

.claude/skills/<skill-folder>/
├── SKILL.md
└── [optional supporting files/scripts]

The SKILL.md file is the only required component — a minimal Skill could contain just this file. You can add any supporting resources your Skill needs: documentation files, code templates, configuration examples, or reference data. These additional resources make the Skill more powerful by giving Claude concrete references and executable code to work with.

Let's build a matplotlib assistant Skill for your penguin visualization project. This Skill will help create visualizations using project templates and styling standards. Here is the complete directory structure:

.claude/skills/
└── matplotlib-assistant/
    ├── SKILL.md
    ├── STYLE_GUIDE.md
    ├── TEMPLATES.md
    └── templates/
        ├── multi_panel.py
        ├── publication.py
        └── quick_plot.py

Inside our matplotlib-assistant folder, we have:

• SKILL.md: The required core file containing metadata and instructions
• STYLE_GUIDE.md: Documentation for visual standards like colors, fonts, and dimensions
• TEMPLATES.md: Reference guide explaining available templates and their use cases
• templates/: Directory of ready-to-use Python scripts for different visualization needs

We'll start by writing the SKILL.md file, which defines how Claude discovers and uses this Skill.

Every SKILL.md file begins with YAML frontmatter enclosed between triple dashes (---). As a reminder from the previous lesson, YAML frontmatter is a block of metadata at the top of a Markdown file. For Skills, two fields are essential:

• name: A short, descriptive identifier for the Skill
• description: A sentence explaining what this Skill does and when it applies

The description is especially important because it guides Claude's triggering decisions. When you ask Claude something, it reads these descriptions to determine which Skills are relevant. A clear, specific description helps Claude match your request accurately.

Below the frontmatter, the body contains instructions that Claude follows when this Skill is triggered. Good Skill instructions are clear and sequential, specific about expectations, and connected to bundled resources by filename.

Here is the complete SKILL.md for our matplotlib assistant:

---
name: matplotlib-assistant
description: Creates professional matplotlib visualizations with best practices. Use when the user needs to create plots, charts, graphs, or any data visualization with matplotlib or Python plotting libraries.
---

# Matplotlib Assistant

This skill helps create high-quality matplotlib visualizations by providing templates, style guidance, and best practices.

## When to Use This Skill

Activate when the user wants to:
- Create any type of plot or chart (line, scatter, bar, histogram, heatmap, etc.)
- Visualize data using Python
- Improve existing matplotlib plots
- Get recommendations for plot types
- Apply professional styling to figures
- Export plots for papers, presentations, or web

## Workflow

### 1. Understand Requirements

Ask the user clarifying questions:
- **What type of data?** (time series, distributions, comparisons, relationships, etc.)
- **What's the purpose?** (exploration, presentation, publication, web display)
- **What's the audience?** (technical, general, academic)
- **Any specific requirements?** (size, format, color schemes, accessibility needs)

### 2. Recommend Plot Type

Based on the data and purpose, suggest appropriate visualization:
- **Time series / trends**: Line plots
- **Distributions**: Histograms, box plots, violin plots
- **Comparisons**: Bar charts, grouped bars
- **Relationships**: Scatter plots, correlation heatmaps
- **Proportions**: Pie charts (use sparingly), stacked bars
- **Multiple variables**: Multi-panel figures, subplots

### 3. Provide Template

Reference the appropriate template from [TEMPLATES.md](TEMPLATES.md):
- Start with working code from templates
- Customize for user's specific data structure
- Include clear variable names and comments

### 4. Apply Best Practices

Consult [STYLE_GUIDE.md](STYLE_GUIDE.md) for:
- Appropriate figure sizes
- Font sizes and styling
- Color schemes (especially for accessibility)
- Labels, titles, and legends
- Spacing and layout
- Export settings

### 5. Iterate and Refine

- Show the code and explain key customization points
- Offer to adjust styling, labels, or layout
- Help troubleshoot any issues

## Quick Reference

### Template Files

Located in `templates/` directory:
- **quick_plot.py**: Fast single plot template
- **multi_panel.py**: Multiple subplots in one figure
- **publication.py**: Publication-ready with all bells and whistles

Notice how the instructions define a clear workflow with numbered steps. The Skill references bundled files like TEMPLATES.md and STYLE_GUIDE.md so Claude knows where to find detailed guidance. The "When to Use This Skill" section helps Claude understand exactly which requests should trigger this capability.

The STYLE_GUIDE.md file captures your project's visual standards in a format Claude can reference when generating or reviewing code. Here is a preview of the style guide for our matplotlib assistant:

# Matplotlib Style Guide

Best practices for creating professional, accessible visualizations.

## Figure Dimensions

| Use Case | Size (inches) | Aspect Ratio |
|----------|---------------|--------------|
| Exploration | 10 x 6 | 5:3 |
| Presentation (16:9) | 12 x 6.75 | 16:9 |
| Publication (single column) | 3.5 x 2.5 | 7:5 |
| Publication (double column) | 7 x 5 | 7:5 |

## Font Sizes
# Readable defaults
plt.rcParams.update({
    'font.size': 12,
    'axes.labelsize': 14,
    ...
})

## Color Palettes

### Accessible (Colorblind-Safe)
# IBM Design colorblind-safe palette
COLORS_ACCESSIBLE = [
    '#648FFF',  # Blue
    '#DC267F',  # Magenta
    ...
]

...

The full style guide includes sections on sequential colormaps, export settings for different contexts, layout best practices, and common mistakes to avoid. When Claude applies the Skill, it reads this document to ensure all generated code follows your established conventions.

The remaining files complete the Skill by providing template documentation and executable code:

• TEMPLATES.md describes each template in the templates/ directory, explaining when to use each one and what customization points are available. This helps Claude match user requests to the appropriate starting point.

• templates/quick_plot.py provides minimal setup for rapid data exploration during analysis sessions.

• templates/multi_panel.py handles subplot management for comparing multiple variables or species side-by-side.

• templates/publication.py includes full styling, annotations, and high-resolution export settings for final deliverables.

By bundling executable templates, you give Claude concrete starting points that already encode your standards. Claude can provide these directly or adapt them for specific user needs.

In Lesson 1, you learned how the CLAUDE.md file provides context that loads at the start of every session. This approach works well for information Claude should always know — like your basic color palette or coding conventions. However, loading extensive detail about every possible task would overwhelm Claude's context window and slow down simple requests.

Skills solve this problem through progressive disclosure. Claude learns about your Skills at a high level by reading their names and descriptions. This metadata is lightweight — just a sentence or two per Skill. The full instructions and bundled resources load only when Claude determines a Skill is relevant to your current request.

This layered approach keeps your base context lean. Your CLAUDE.md might contain your core color palette, but the detailed templates, style documentation, and code examples live in Skills. Claude accesses them on-demand — only when you are actually working on tasks that require them.

With the Skill in place, here is how an interaction begins. While Skills are designed to trigger automatically based on the context of your request, you can also explicitly mention a Skill by name to ensure Claude uses a specific toolset—this is especially helpful during development to ensure consistent behavior.

Note: While Claude is excellent at semantic matching, it may sometimes need a "nudge" to trigger a specific Skill if the request is broad. Explicitly mentioning the Skill name (as shown below) ensures Claude loads the specific instructions and resources you've provided.

> Using the matplotlib-assistant skill, create a scatter plot from penguins.csv 
  showing bill length vs flipper length, colored by species.

● I'll use the matplotlib-assistant skill to create that scatter plot for you.

● /matplotlib-assistant

  Use skill "matplotlib-assistant"?
  Claude may use instructions, code, or files from this Skill.

    Creates professional matplotlib visualizations with best practices. 
    Use when the user needs to create plots, charts, graphs, or any data 
    visualization with matplotlib or Python plotting libraries. (project)

  Do you want to proceed?
  ❯ 1. Yes
    2. Yes, and don't ask again for matplotlib-assistant in /usercode/FILESYSTEM
    3. No, and tell Claude what to do differently (esc)

Notice the permission prompt that appears when Claude first uses a Skill. This works just like a tool call — Claude recognizes that your request matches the Skill's description (or your explicit request) and requests permission to load its instructions and resources. This gives you control over which Skills can execute and when.

Once you approve the Skill, Claude follows the workflow defined in SKILL.md. Here is the rest of the interaction:

● I'll help you create a scatter plot from the penguins dataset. Let me first 
  check if the file exists and examine its structure.

● Read(penguins.csv)
  ⎿  Read 10 lines

● Great! I can see the penguins dataset with bill_length_mm and flipper_length_mm 
  columns, plus species information. Let me create a professional scatter plot 
  for you.

● Write(penguin_scatter.py)
  ⎿  Wrote 64 lines to penguin_scatter.py

● Now let me run the script to create your visualization:

● Bash(python penguin_scatter.py)
  ⎿  Scatter plot saved as 'penguin_scatter.png'

● Perfect! I've successfully created a professional scatter plot showing the 
  relationship between bill length and flipper length for three penguin species.

  Key Features:
  - Three distinct species clusters: Adelie (blue), Chinstrap (orange), 
    and Gentoo (green)
  - Colorblind-friendly palette for accessibility
  - High-resolution output (300 DPI) suitable for presentations or publications

  Would you like me to adjust anything about the plot?

The resulting visualization demonstrates how Claude applied the Skill's guidelines:

Notice how the output follows the STYLE_GUIDE.md conventions: the colorblind-safe palette from COLORS_ACCESSIBLE, clean axes with hidden top and right spines, proper labels with units, and a legend positioned outside the data area. Claude generated code that embodies your project standards without you having to specify each detail — the Skill provided that guidance automatically.

You have learned how to build Agent Skills that give Claude specialized capabilities it can apply automatically. Skills are model-triggered and live in .claude/skills/, with YAML frontmatter guiding discovery and bundled resources keeping everything self-contained. Progressive disclosure ensures Claude loads Skill content on-demand, keeping your base context lean while enabling deep expertise.

In the upcoming practice exercises, you will build your own visualization Skills from scratch. You will create Skills that help with chart creation, apply styling standards, and provide appropriate templates — all triggered automatically when Claude recognizes the relevant context. Get ready to give Claude deep visualization expertise that activates exactly when you need it.