# Silhouette Score

> Compute the silhouette_score metric — provided by scikit-learn. Use when the user has predictions and ground-truth and needs to compute silhouette_score, or asks how to score with silhouette_score.

- Skill: `qhjqhj00/silhouette-score` (Agent Skill)
- Install (CLI): `npx skillmds add qhjqhj00/silhouette-score`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qhjqhj00/silhouette-score/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: qhjqhj00 (https://skillmd.com/u/qhjqhj00)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/qhjqhj00/silhouette-score

---


# silhouette-score

> Metric `silhouette_score` from `scikit-learn` (sklearn.metrics.silhouette_score)

## When to invoke this skill

The user has predictions + ground truth and asks to evaluate with silhouette_score, or
mentions `sklearn.metrics.silhouette_score` directly, or wants the standard scikit-learn implementation.

## Reference signature

```python
from sklearn.metrics import silhouette_score

# silhouette_score(X, labels, *, metric='euclidean', sample_size=None, random_state=None, **kwds)
```

## Library docstring

```
Compute the mean Silhouette Coefficient of all samples.

The Silhouette Coefficient is calculated using the mean intra-cluster
distance (``a``) and the mean nearest-cluster distance (``b``) for each
sample.  The Silhouette Coefficient for a sample is ``(b - a) / max(a,
b)``.  To clarify, ``b`` is the distance between a sample and the nearest
cluster that the sample is not a part of.
Note that Silhouette Coefficient is only defined if number of labels
is ``2 <= n_labels <= n_samples - 1``.

This function returns the mean Silhouette Coefficient over all samples.
To obtain the values for each sample, use :func:`silhouette_samples`.

The best value is 1 and the worst value is -1. Values near 0 indicate
overlapping clusters. Negative values generally indicate that a sample has
been assigned to the wrong cluster, as a different cluster is more similar.

Read more in the :ref:`User Guide <silhouette_coefficient>`.

Parameters
----------
X : {array-like, sparse matrix} of shape (n_samples_a, n_samples_a) if metric ==             "precomputed" or (n_samples_a, n_features) otherwise
    An array of pairwise distances between samples, or a feature array.

labels : array-like of shape (n_samples,)
    Predicted labels for each sample.

metric : str or callable, default='euclidean'
    The metric to use when calculating distance between instances in a
    feature array. If metric is a string, it must be one of the options
    allowed by :func:`~sklearn.metrics.pairwise_distances`. If ``X`` is
    the distance array itself, use ``metric="precomputed"``.

sample_size : int, default=None
    The size of the sample to use when computing the Silhouette Coefficient
    on a random subset of the data.
    If ``sample_size is None``, no sampling is used.

random_state : int, RandomState instance or None, default=None
    Determines random number generation for selecting a subset of samples.
    Used when ``sample_size is not None``.
    Pass an int for reproducible results across multiple function calls.
    See :term:`Glossary <random_state>`.

**kwds : optional keyword parameters
    Any further parameters are passed directly to the distance function.
    If using a scipy.spatial.
```

## Quick recipe

```python
import sklearn.metrics as _m
score = _m.silhouette_score(y_true, y_pred)
```

## Don'ts

- Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
- Always check the library version's argument order — sklearn is `(y_true, y_pred)` while torchmetrics is `(preds, target)`.