Skip to main content
skill CX Codex

plotly · tondevrel — Claude Code skill: what it does, how to install

Teaches your coding agent to produce interactive Python visualizations with Plotly Express and Graph Objects. Useful for dashboards and data notebooks.

MIT 213 installs ★ 25 updated 2026-02-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add tondevrel/scientific-agent-skills --skill plotly -a claude-code
Open on GitHub

What plotly does

The skill equips the agent with guidelines for Python visualization in version 5.18. It directs the model to default to Plotly Express for tidy DataFrames while reserving Graph Objects for complex custom layers, multi-axis layouts, or 3D surfaces. The guidance prevents clumsy loops over traces and keeps code concise.

Supported formats include geographic choropleths with Mapbox, financial candlestick charts, facet subplots, and interactive timelines. Visualizations can be exported as standalone HTML documents using fig.write_html.

Running the generated code requires plotly and pandas installed in Python. If your pipeline demands static LaTeX figures or operates under strict memory limits, Plotly is the wrong choice because its JSON data structures consume substantial memory.

What it helps with

  • Create interactive scatter and line charts with tooltips
  • Render 3D surfaces and scatter plots from Python data
  • Generate geographic maps with Mapbox styling
  • Export interactive dashboards to self-contained HTML files

Example prompts for the agent

  • Build an interactive scatter plot with marginal boxplots using Plotly Express
  • Generate a 3D surface visualization from an elevation matrix with Graph Objects
  • Plot a financial candlestick chart from this daily stock DataFrame

How to install plotly

1Skills CLI (Vercel)

npx skills add tondevrel/scientific-agent-skills --skill plotly -a claude-code

2Manually: put the files in place

~/.claude/skills/plotly/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/plotly/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about plotly

How to install plotly in Claude Code?

Run npx skills add tondevrel/scientific-agent-skills --skill plotly -a claude-code in your terminal. This writes the skill definition to ~/.claude/skills/plotly/SKILL.md.

When does the skill choose Graph Objects over Plotly Express?

Plotly Express is favored for quick exploratory work with tidy tables, whereas Graph Objects handles low-level figure control and custom 3D surface traces.

What dependencies are needed to run the resulting code?

Your Python environment needs plotly and pandas installed via pip install plotly pandas.

Source text

SKILL.md · MIT
---
name: plotly
description: A high-level interactive graphing library for Python. Ideal for web-based visualizations, 3D plots, and complex interactive dashboards. Built on plotly.js, it allows users to zoom, pan, and hover over data points in a browser-based environment. Use for interactive charts, web applications, Jupyter notebooks, 3D data visualization, geographic maps, financial charts, animations, time-series analysis, and building production-ready dashboards with Dash.
version: 5.18
license: MIT
---

# Plotly - Interactive Visualization

Plotly provides a wide range of interactive charts. Its "Plotly Express" API is designed for speed and ease of use with tidy DataFrames, while "Graph Objects" offers low-level control over every trace and attribute.

## When to Use

- Creating interactive charts for web applications or Jupyter notebooks
- Visualizing 3D data (surfaces, scatter, mesh)
- Geographic maps (scatter on maps, choropleths) with Mapbox integration
- Financial charts (candlestick, OHLC)
- Exploring large datasets where zooming into specific regions is required
- Creating animations (time-series sliders)
- Building production-ready dashboards (via Dash)

## Reference Documentation

**Official docs**: https://plotly.com/python/  
**Plotly Express**: https://plotly.com/python/plotly-express/  
**Search patterns**: `px.scatter`, `go.Figure`, `fig.update_layout`, `fig.write_html`, `px.choropleth`

## Core Principles

### Plotly Express (px) vs. Graph Objects (go)

| Feature | Plotly Express (px) | Graph Objects (go) |
|---------|---------------------|-------------------|
| Complexity | High-level, concise. | Low-level, verbose. |
| Data Format | Tidy (long-form) DataFrames. | Lists, Arrays, Dicts, or DataFrames. |
| Customization | Good (using update_*). | Maximum / Full control. |
| Speed of Dev | Very fast. | Slower. |

### Use Plotly For

- Interactive exploration (hover, zoom)
- 3D and Geospatial visualization
- Exporting to standalone interactive HTML files
- Integration with Dash

### Do NOT Use For

- Publication-quality static LaTeX plots (use Matplotlib)
- Very large static image generation (Matplotlib is faster)
- Low-memory environments (Plotly's JSON-based figures are memory-heavy)

## Quick Reference

### Installation

```bash
pip install plotly pandas
```

### Standard Imports

```python
import plotly.express as px
import plotly.graph_objects as go
import pandas as pd
import numpy as np
```

### Basic Pattern - Plotly Express

```python
import plotly.express as px

# Load data
df = px.data.iris()

# Create interactive scatter plot
fig = px.scatter(df, x="sepal_width", y="sepal_length", 
                 color="species", size="petal_length",
                 hover_data=['petal_width'])

# Display
fig.show()
```

## Critical Rules

### ✅ DO

- Use Plotly Express first - 90% of tasks are easier with px
- Prefer Tidy Data - Ensure one row per observation for easy mapping to colors/axes
- Use update_layout - Cleanly modify titles, fonts, and background colors
- Save as HTML - Use `fig.write_html("plot.html")` to share interactive charts
- Leverage Hover Data - Add context to points without cluttering the plot
- Set Figure Templates - Use `template="plotly_dark"` or `"ggplot2"` for instant style
- Use marginal_x/y - In px.scatter, quickly add histograms or boxplots to margins

### ❌ DON'T

- Pass huge datasets to the browser - Plotting >50k points can lag the UI; use datashader or decimation
- Manual looping with go - If px can do it, don't use a for-loop to add traces in go
- Forget to set axis labels - px uses column names; rename them in the DataFrame for better labels
- Over-animate - Smooth animations are cool, but too many moving parts distract from the data

## Anti-Patterns (NEVER)

```python
# ❌ BAD: Over-complicating a simple plot with Graph Objects
fig = go.Figure()
for species in df['species'].unique():
    sub = df[df['species'] == species]
    fig.add_trace(go.Scatter(x=sub['sepal_w'], y=sub['sepal_l'], name=species))

# ✅ GOOD: Use Plotly Express (One line, automatic legend/colors)
fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species")

# ❌ BAD: Mixing list-style data with DataFrame-style data in px
px.scatter(x=[1,2,3], y=df['column']) # Can lead to alignment issues

# ✅ GOOD: Stick to the DataFrame
px.scatter(df, x="column_a", y="column_b")
```

## Plotly Express (px) Deep Dive

### Statistical Charts

```python
# Boxplot with points
fig = px.box(df, x="day", y="total_bill", color="smoker", points="all")

# Violin plot with box inside
fig = px.violin(df, x="day", y="total_bill", color="sex", box=True, points="all")

# Heatmap (Density Contour)
fig = px.density_heatmap(df, x="total_bill", y="tip", marginal_x="histogram", marginal_y="histogram")
```

### Time Series and Faceting

```python
df = px.data.stocks()
# Multiple lines from wide data
fig = px.line(df, x='date', y=["GOOG", "AAPL", "AMZN"], title="Tech Stocks")

# Faceting (Subplots by category)
df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", color="smoker", 
                 facet_col="day", facet_row="time")
```

## 3D Visualization

### Scatter, Lines, and Surfaces

```python
# 3D Scatter
fig = px.scatter_3d(df, x='sepal_length', y='sepal_width', z='petal_width', color='species')

# 3D Surface (Using Graph Objects)
z_data = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/api_docs/mt_bruno_elevation.csv')
fig = go.Figure(data=[go.Surface(z=z_data.values)])
fig.update_layout(title='Mt Bruno Elevation', autosize=False,
                  width=500, height=500, margin=dict(l=65, r=50, b=65, t=90))
```

## Geospatial Analysis

### Maps and Choropleths

```python
# Scatter on a map
df = px.data.gapminder().query("year == 2007")
fig = px.scatter_geo(df, locations="iso_alpha", color="continent",
                     hover_name="country", size="pop",
                     projection="natural earth")

# Detailed Mapbox Choropleth (Needs token or use open-street-map)
fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
                           color_continuous_scale="Viridis",
                           mapbox_style="carto-positron",
                           zoom=3, center = {"lat": 37.0902, "lon": -95.7129})
```

## Layout and Styling (fig.update_*)

### Fine-tuning the appearance

```python
fig = px.scatter(df, x="x", y="y")

# Global layout updates
fig.update_layout(
    title="Custom Styled Plot",
    xaxis_title="Dimension X",
    yaxis_title="Dimension Y",
    font=dict(family="Courier New, monospace", size=18, color="RebeccaPurple"),
    legend=dict(yanchor="top", y=0.99, xanchor="left", x=0.01),
    plot_bgcolor="white"
)

# Axis specific updates
fig.update_xaxes(showgrid=True, gridwidth=1, gridcolor='LightPink')
fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='Black')
```

## Advanced Interaction: Animations

```python
df = px.data.gapminder()
fig = px.scatter(df, x="gdpPercap", y="lifeExp", animation_frame="year", 
                 animation_group="country",
                 size="pop", color="continent", hover_name="country",
                 log_x=True, size_max=55, range_x=[100, 100000], range_y=[25, 90])
```

## Practical Workflows

### 1. Interactive Scientific Report Export

```python
def create_interactive_report(df, filename="report.html"):
    """Generates a multi-chart HTML report."""
    fig1 = px.scatter(df, x="A", y="B", color="C")
    fig2 = px.histogram(df, x="A", color="C")
    
    with open(filename, 'a') as f:
        f.write(fig1.to_html(full_html=False, include_plotlyjs='cdn'))
        f.write(fig2.to_html(full_html=False, include_plotlyjs='cdn'))

# Useful for sharing findings with non-technical stakeholders
```

### 2. Financial Dashboard Fragment (Candlestick)

```python
import pandas as pd
from datetime import datetime

df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')

fig = go.Figure(data=[go.Candlestick(x=df['Date'],
                open=df['AAPL.Open'],
                high=df['AAPL.High'],
                low=df['AAPL.Low'],
                close=df['AAPL.Close'])])

# Remove rangeslider for cleaner look
fig.update_layout(xaxis_rangeslider_visible=False)
```

### 3. Mixing Subplots with go.Figure

```python
from plotly.subplots import make_subplots

fig = make_subplots(rows=1, cols=2, subplot_titles=("Plot A", "Plot B"))

fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
fig.add_trace(go.Bar(x=[1, 2, 3], y=[2, 3, 5]), row=1, col=2)

fig.update_layout(height=600, width=800, title_text="Side-by-Side Comparison")
```

## Performance Optimization

### WebGL for Large Datasets

```python
# For scatter plots with >10,000 points, use Scattergl (Graph Objects)
# or tell px to use webgl (available in newer versions)
fig = px.scatter(df, x="large_x", y="large_y", render_mode="webgl")

# WebGL drastically improves performance by using the GPU for rendering.
```

## Common Pitfalls and Solutions

### JSON Overhead in Notebooks

```python
# ❌ Problem: Notebook file size explodes to 50MB
# ✅ Solution: Display as static image (requires kaleido) or use a different renderer
# fig.show(renderer="png") # Static
# OR: Clear output after viewing
```

### Axis Scaling in Animations

```python
# ❌ Problem: Axes jump around during animation
# ✅ Solution: Manually fix the ranges
fig = px.scatter(df, x="x", y="y", animation_frame="time",
                 range_x=[0, 100], range_y=[0, 100])
```

### Handling Missing Categories in Legend

```python
# ❌ Problem: Colors change when filtering data because categories disappear
# ✅ Solution: Pass a category_orders dictionary
fig = px.scatter(df, x="x", y="y", color="category",
                 category_orders={"category": ["A", "B", "C", "D"]})
```

## Best Practices

1. **Use Plotly Express first** - Start with `px` for 90% of tasks; only use `go` when you need fine-grained control
2. **Work with tidy DataFrames** - Ensure one row per observation for easy mapping to visual attributes
3. **Use `update_layout` for styling** - Cleanly modify titles, fonts, and background colors without recreating figures
4. **Save as HTML for sharing** - Use `fig.write_html("plot.html")` to share interactive charts with stakeholders
5. **Leverage hover data** - Add context to points without cluttering the plot
6. **Set figure templates** - Use `template="plotly_dark"` or `"ggplot2"` for instant professional styling
7. **Use marginal plots** - In `px.scatter`, use `marginal_x` and `marginal_y` to quickly add histograms or boxplots
8. **Optimize for large datasets** - Use WebGL rendering or datashader for datasets with >50k points
9. **Fix axis ranges in animations** - Use `range_x` and `range_y` to prevent axes from jumping during animations
10. **Set category orders** - Use `category_orders` to maintain consistent colors when filtering data

Plotly bridges the gap between static analysis and interactive discovery. It is the best tool for moving scientific insights from a notebook to the web.

© tondevrel · MIT · tondevrel/scientific-agent-skills

Similar skills

All skills for Data and databases →

plotly by other authors comes first.

plotly davila7 Teaches Claude Code to generate interactive Python charts, multi-panel dashboards, and statistical plots with Plotly. CX Codex +1 383installs evident-charts Randy Olson evident-charts is a Claude Code skill for building and reviewing explanatory data charts. It activates for chart edits, critiques, and chart-image questions. CX Codex +1 ★ 63repo stars csv-data-visualizer ailabs-393 csv-data-visualizer creates interactive Plotly charts from CSV tables, profiles dataset quality, and generates multi-plot dashboards. Useful for exploratory data analysis. CX Codex +1 1,300installs Scientific Data Visualizer devisasari Scientific Data Visualizer is a prompt for ChatGPT and Claude.ai that configures the model as a scientific data visualization specialist. It builds charts and interactive dashboards from complex datasets. GP ChatGPT ★ 178,201repo stars data-visualization official anthropics data-visualization selects chart types based on data structure and produces Python visualization code in matplotlib, seaborn, and plotly. Useful for reports and research figures. CX Codex +1 15,100installs create-viz official anthropics create-viz generates publication-quality charts from tables and database queries using Python. Selects chart type, formats axes, and saves PNG for reports and presentations. CX Codex +1 5,400installs downtrend-duration-analyzer tradermonty downtrend-duration-analyzer — a skill for Claude Code and five other platforms that processes historical price data to find peak-to-trough periods and outputs interactive HTML histograms broken down by sector and market cap tier. CX Codex +1 3,400installs

From the same set11

The whole set →

Project sponsors

Companies that keep this analytics open