Guide · Agent skill
How to use the UMAP dimensionality reduction agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to add the umap-learn agent skill to an AI coding agent, ask for it in plain language, and get working Python code for UMAP, a method that compresses high-dimensional data (many columns per row) into two or a few dimensions. It is written for data scientists, developers and students who may never have used an agent skill before. By the end you will know what the skill changes, how to install it, how to phrase requests and which cautions to keep in mind when reading the result.
UMAP Dimensionality ReductionK-Dense-AI/scientific-agent-skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the umap-learn ZIP from this page and unzip it so you have a folder containing SKILL.md.
- 2Place the folder. Move it to ~/.claude/skills/ for all projects or into your project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Install Python packages. Run uv pip install umap-learn==0.5.12 in an environment running Python 3.9 or newer.
- 4Describe your data and goal. Tell the agent the shape of your data, the data type and whether you want a plot, clusters or model features.
- 5Review the settings and code. Check the n_neighbors, min_dist, n_components and metric values the agent chose and why.
- 6Verify the embedding. Compare the embedding with the original data, test sensitivity to seeds and parameters, and keep test data out of preprocessing.
What does the umap-learn skill make the agent do?
Without the skill, an agent can still write UMAP code, but it may choose settings at random or skip checks. With the skill loaded, the agent follows the skill's guidance on UMAP for nonlinear dimensionality reduction, 2D and 3D embeddings, clustering preprocessing, supervised or semi-supervised UMAP, DensMAP, AlignedUMAP and Parametric UMAP workflows.
In practice the agent picks settings such as neighbourhood size (n_neighbors), minimum distance (min_dist) and metric for the kind of data you describe, writes the Python code, and reminds you of cautions: check results against the original data, keep test data out of preprocessing, and do not read exact distances or cluster sizes off the picture as if they were measurements.
Install the umap-learn skill from the download ZIP
Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md and references/api_reference.md. Place the unzipped folder in one of these locations:
- Personal skills for all your projects: ~/.claude/skills/
- Single project only: the .claude/skills/ folder inside your project
- Claude apps: upload the ZIP under Settings → Capabilities → Skills
Install the Python packages the skill needs
The skill targets Python 3.9 or newer and depends on umap-learn with scikit-learn, numba, pynndescent, numpy and scipy. The skill's own example pins umap-learn to 0.5.12 using uv, so you can match it exactly. Optional extras are HDBSCAN, Matplotlib, and TensorFlow with Keras 3 for Parametric UMAP.
uv pip install umap-learn==0.5.12Trigger the skill with natural requests
You do not need special syntax. Describe your data and goal in ordinary words, and mention UMAP if you want to be sure the skill is used. The skill is a good fit for high-dimensional tables such as gene expression or survey features, and for document vectors when you want cosine distance.
Give the agent what it needs to choose settings: the number of rows and columns, whether the columns are numeric, binary or text-derived, and whether you want a plot, clusters or features for a model.
- Make a 2D UMAP plot of my gene expression matrix, colour points by cell type, and explain the settings you chose.
- Reduce my survey data to 10 dimensions so I can cluster it with HDBSCAN.
- Embed these binary presence/absence features with UMAP using a suitable metric.
- Show me how UMAP differs from PCA on this dataset and what I should be careful about.
Example: a visualisation workflow
The skill's typical workflow scales the features, fits UMAP with explicit settings and plots the result. Scaling matters: for numeric Euclidean-style distances it changes how much each feature counts, so decide whether it is appropriate for your data. In the example below, raw_data is your samples-by-features table and labels follow the same row order.
- n_neighbors=15 and min_dist=0.1 are the skill's starting point for visualisation.
- Use min_dist=0.0 and about 10 components when the goal is clustering rather than a picture.
- Fit preprocessing on training data only when the work is predictive.
import umap
import matplotlib.pyplot as plt
from sklearn.preprocessing import StandardScaler
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)
reducer = umap.UMAP(
n_neighbors=15,
min_dist=0.1,
n_components=2,
metric='euclidean',
random_state=42
)
embedding = reducer.fit_transform(scaled_data)
plt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('UMAP Embedding')
plt.show()Choose settings for your data type
The skill recommends different settings for different goals. Use n_components=2 for visualisation, 5 to 10 for clustering preprocessing, and higher values for feature engineering before a downstream model. For text or document vectors, use the cosine metric; for binary data, use a binary metric such as hamming or jaccard.
For supervised work, pass labels through y. For semi-supervised work, encode known classes as nonnegative integers and mark unlabeled points as -1, which applies to categorical targets.
- Visualisation: n_neighbors=15, min_dist 0.1 to 0.3, n_components=2
- Clustering: n_neighbors=30, min_dist=0.0, n_components=10
- Document embeddings: metric='cosine'
- Broader structure: n_neighbors around 100 with min_dist around 0.5
Read the result with care
UMAP axes, the area of islands and the gaps between clusters have no calibrated physical or probabilistic meaning. Do not read exact distances or cluster sizes off the picture as measurements. Before you trust an embedding, the skill suggests checking finite coordinates, whether neighbourhoods are retained, how sensitive the result is to random seeds and parameters, and whether it matches domain evidence in the original space.
Labels used for supervised UMAP shape the embedding by design, so the separation they produce is not independent proof that real classes exist. Tune on training folds and evaluate on held-out samples.
What people use it for
- Visualising gene expression matrices to see whether cells group by type.
- Reducing survey feature columns to a few dimensions before clustering with HDBSCAN.
- Embedding text or document vectors with the cosine metric for exploration.
- Comparing UMAP against PCA or t-SNE on a dataset to learn how the methods differ.
- Building feature-engineering steps in a Python pipeline for a downstream model.
Frequently asked questions
How do I install the umap-learn agent skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
What does the umap-learn skill require?
It requires Python 3.9 or newer and umap-learn with its dependencies scikit-learn, numba, pynndescent, numpy and scipy. HDBSCAN, Matplotlib and TensorFlow with Keras 3 are optional, with TensorFlow needed for Parametric UMAP.
Is the umap-learn skill free?
The skill is listed under the MIT licence on this page. The source SKILL.md file names a BSD-3-Clause licence, so check the licence file in the download if you need to confirm which terms apply.
Does the skill run code and use the network?
Yes on both counts. The skill runs scripts and uses the network, which the source says is needed for installation rather than local fitting. Review any code before running it on sensitive data.
How is UMAP different from PCA and t-SNE?
UMAP is a nonlinear method that scales well in the number of output dimensions, unlike t-SNE, so it can be used beyond visualisation. PCA is linear. In all three cases, the layout distances are not calibrated measurements, so verify results against the original data.
What are the alternatives to this skill?
You can ask an agent to write UMAP code without the skill, or use t-SNE or PCA for simpler or linear reduction. The skill's advantage is the guidance on settings and cautions; it does not replace checking the results yourself.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you are a data scientist, developer or student who wants an agent to set up UMAP embeddings in Python with sensible settings and clear warnings about interpretation. Pick something else if you need calibrated or physically meaningful distances between clusters, because UMAP layout distances are not quantitatively reliable, or if you cannot carefully check the pipeline for test-data leakage.
Download the skill