matplotlib
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill matplotlibRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/matplotlibInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/matplotlib/ - All projects
~/.claude/skills/matplotlib/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Matplotlib visualization assistance covering figure subplots, custom styling, colormaps, and publication-ready charts. Use when creating static or publication scientific figures in Python.
Matplotlib
Matplotlib is the grandfather of Python plotting. It is verbose but provides infinite control.
When to Use
- Publication-Quality Scientific Plotting: Generating exact, reproducible figures for academic papers, documentation, and reports.
- Fine-Grained Custom Visualizations: Complete control over every pixel, tick, axis spine, legend, and colorbar.
- Headless Server-Side Chart Rendering: Generating PNG, SVG, and PDF visualizations in backend microservices without GUI displays.
- Subplot Grid Layouts: Assembling multi-panel visual figure grids with
GridSpec.
Quick Start
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y1 = np.sin(x)
y2 = np.cos(x)
fig, ax = plt.subplots(figsize=(8, 4), dpi=100)
ax.plot(x, y1, label="sin(x)", color="#2563eb", linewidth=2)
ax.plot(x, y2, label="cos(x)", color="#dc2626", linestyle="--")
ax.set_title("Trigonometric Functions")
ax.set_xlabel("Time (s)")
ax.set_ylabel("Amplitude")
ax.legend()
ax.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
Core Concepts
Object-Oriented Subplots & Modern Styling
Building clean, publication-ready multi-axis figures:
import matplotlib.pyplot as plt
import numpy as np
# Use non-interactive backend for server environments
import matplotlib
matplotlib.use('Agg')
# Set modern styling parameters
plt.style.use('seaborn-v0_8-whitegrid' if 'seaborn-v0_8-whitegrid' in plt.style.available else 'default')
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5), dpi=300)
x = np.linspace(0, 10, 200)
y1 = np.sin(x) * np.exp(-0.1 * x)
y2 = np.cos(x) * np.exp(-0.1 * x)
# Panel 1: Line plot with error bands
ax1.plot(x, y1, color='#2563eb', lw=2, label='Damped Sine')
ax1.fill_between(x, y1 - 0.2, y1 + 0.2, color='#2563eb', alpha=0.15)
ax1.set_title("Signal Decay", fontsize=12, fontweight='bold')
ax1.set_xlabel("Time (seconds)")
ax1.set_ylabel("Amplitude")
ax1.legend(loc='upper right')
# Panel 2: Distribution histogram
data = np.random.normal(loc=0, scale=1, size=1000)
ax2.hist(data, bins=30, color='#10b981', edgecolor='white', alpha=0.85)
ax2.set_title("Residual Distribution", fontsize=12, fontweight='bold')
ax2.set_xlabel("Value")
ax2.set_ylabel("Frequency")
plt.tight_layout()
fig.savefig("metrics_figure.png", dpi=300, bbox_inches='tight')
plt.close(fig)
Secondary Twin Axis (twinx)
Plotting two metrics with different scales on the same chart:
fig, ax1 = plt.subplots(figsize=(8, 4.5))
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']
revenue = [120, 145, 160, 190, 210, 250]
churn_rate = [2.4, 2.1, 1.9, 1.8, 1.5, 1.2]
# Primary axis: Bar chart
bars = ax1.bar(months, revenue, color='#4f46e5', alpha=0.7, width=0.5, label='Revenue ($k)')
ax1.set_ylabel('Revenue in Thousands ($)', color='#4f46e5')
ax1.tick_params(axis='y', labelcolor='#4f46e5')
# Secondary axis: Line plot
ax2 = ax1.twinx()
line = ax2.plot(months, churn_rate, color='#ef4444', lw=3, marker='o', label='Churn Rate (%)')
ax2.set_ylabel('Churn Rate (%)', color='#ef4444')
ax2.tick_params(axis='y', labelcolor='#ef4444')
ax2.grid(False) # Prevent overlapping grid lines
plt.title("Revenue Growth vs. Churn Reduction (2026)")
plt.savefig("revenue_churn.png", bbox_inches='tight')
plt.close(fig)
Heatmaps & Custom Colormaps
Visualizing correlation matrices or loss surfaces:
matrix = np.corrcoef(np.random.randn(8, 100))
fig, ax = plt.subplots(figsize=(6, 5))
cax = ax.matshow(matrix, cmap='coolwarm', vmin=-1, vmax=1)
fig.colorbar(cax)
ax.set_xticks(range(8))
ax.set_yticks(range(8))
ax.set_title("Correlation Heatmap", pad=20)
plt.savefig("heatmap.png", bbox_inches='tight')
plt.close(fig)
Common Patterns
Clean Multi-Panel Subplots with Shared Axes
Problem: Creating multiple comparative charts where axis ranges must stay aligned.
Solution:
Use plt.subplots with shared axes:
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(8, 6), sharex=True)
ax1.plot(x, y1, color="navy")
ax1.set_ylabel("Raw Signal")
ax2.plot(x, np.abs(y1), color="darkorange")
ax2.set_ylabel("Rectified")
ax2.set_xlabel("Sample")
plt.tight_layout()
Best Practices
Do:
- Use the Object-Oriented interface (
fig, ax = plt.subplots()) instead of statefulplt.plot()calls. - Set
matplotlib.use('Agg')when running inside serverless functions, Docker, or CI without a desktop display. - Always call
plt.close(fig)after saving to disk to prevent memory leaks from accumulated figures. - Save figures with
bbox_inches='tight'to prevent labels and titles from being clipped at margins.
Don't:
- Use rainbow/jet colormaps; use perceptively uniform colormaps (
viridis,plasma,coolwarm). - Rely on default DPI (100); export publication graphics with at least
dpi=300. - Leave gridlines enabled on both axes when using
twinx(); disable one to prevent clutter.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
UserWarning: Matplotlib is currently using agg, which is a non-GUI backend | Attempting plt.show() in headless server/container. | Save figure to disk instead: fig.savefig('output.png'). |
Labels overlapping or cut off | Figure bounding box too tight for tick labels. | Call plt.tight_layout() or use bbox_inches='tight' when saving. |
Memory leak: Figures not closing | Creating figures in loops without calling plt.close(). | Add plt.close(fig) at the end of each loop iteration. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill