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
npx skills add tondevrel/scientific-agent-skills --skill plotly -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/plotly/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/plotly/
1Skills CLI (Vercel)
npx skills add tondevrel/scientific-agent-skills --skill plotly -a codex2Manually: put the files in place
.agents/skills/plotly/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add tondevrel/scientific-agent-skills --skill plotly -a cursor2Manually: put the files in place
.cursor/skills/plotly/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install tondevrel/scientific-agent-skills skills/plotly2Manually: put the files in place
.github/skills/plotly/SKILL.md1Skills CLI (Vercel)
npx skills add tondevrel/scientific-agent-skills --skill plotly -a gemini-cli2Platform CLI
gemini skills install https://github.com/tondevrel/scientific-agent-skills --path skills/plotlyManually: put the files in place
.devin/skills/plotly/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add tondevrel/scientific-agent-skills --skill plotly -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.