Loaded when description matches the task. SKILL.md is the navigator — open only the reference file matching the sub-domain (broadcasting, linalg, random, v2-migration, etc.).
Use this skill when
Working directly with ndarray — creation, reshaping, indexing, slicing, type conversion
Broadcasting between arrays of different shapes — debugging ValueError: operands could not be broadcast
Linear algebra — solve, lstsq, eig/eigh, svd, qr, cholesky, det, norm, einsum
Random number generation — np.random.default_rng(), distributions, reproducible streams, parallel-safe seeding via SeedSequence
Migrating code from NumPy 1.x to 2.x — removed np.int/np.bool/np.float aliases, np.in1d → np.isin, NEP 50 promotion, scalar repr changes
Performance work — vectorization, contiguous memory, np.einsum contractions, views vs copies, releasing the GIL via C ops
Interop — exchanging arrays with pandas / polars / PyTorch / CuPy via zero-copy buffers, DLPack, __array_interface__
File IO of numeric data — .npy / .npz, np.memmap, structured arrays
Do not use this skill when
Working with labeled tabular data (named columns, joins, groupby) — use pandas or polars
Building ML estimators / pipelines / cross-validation — use scikit-learn (it consumes NumPy)
Training neural nets with autograd, optimizers, GPU/MPS — use pytorch (torch.from_numpy for bridge)
GPU-resident arrays as primary store — use cuda-python / CuPy (cupy.asarray(numpy_array) to upload)
Pure Python language questions (type hints, asyncio, packaging) — use python
Pure SQL aggregation already runnable database-side — use postgresql
Purpose
NumPy is the foundational array library for scientific Python — ndarray plus a C-level ufunc machinery, broadcasting rules, linear algebra, FFT, and a modern random Generator API. Everything in the scientific Python stack (pandas, polars, scikit-learn, PyTorch, JAX, CuPy, SciPy) either is a NumPy array under the hood or has zero-copy interop with one. This skill covers the direct-ndarray surface — the layer below DataFrames and tensors.
The NumPy 2.x line introduced significant breaking changes from 1.x: removed Python-typed aliases (np.int, np.bool, np.float, np.object, np.str), a cleaner main namespace (many functions moved or removed — np.in1d, np.cumproduct, np.alltrue, np.sometrue, np.round_, np.product, np.trapz, np.row_stack), NEP 50 dtype promotion (strictly dtype-based, not value-based), new scalar repr (np.float64(3.0) instead of 3.0), and string truthiness matching Python. Code written against 1.x mental models breaks loudly — see v2-migration.md.
Capabilities
Array creation and dtypes
np.array, np.zeros, np.ones, np.empty, np.full, np.arange, np.linspace, np.eye. Dtypes: int8/16/32/64, uint8/16/32/64, float16/32/64, complex64/128, bool_, str_, bytes_, object_, structured dtypes. Attributes: shape, ndim, dtype, itemsize, nbytes, strides, flags. Default integer is int64 on 64-bit platforms (including Windows since 2.0).
Basic slicing returns a view (shares memory). Integer-array (fancy) indexing and boolean masking return a copy. np.ix_ constructs open-mesh indices. ... (ellipsis) and np.newaxis (None) shape selectors. Use arr.base to detect views. Mutating a view propagates; mutating a copy doesn't — the source of most silent NumPy bugs.
Dimensions matched right-to-left. Missing trailing dims treated as 1. Mismatched non-1 dims raise. np.broadcast_to, np.broadcast_shapes, np.broadcast_arrays to materialize. Broadcasting can silently allocate huge intermediates — watch for (N, 1) * (1, N) when only the diagonal is needed (use np.einsum or np.diag patterns).
Element-wise functions (np.add, np.sin, np.exp, ...) with out=, where=, dtype=, casting= parameters. .reduce, .accumulate, .reduceat, and .at (unbuffered in-place). np.vectorize is a convenience wrapper, NOT a speedup — it's a Python-level loop. True vectorization means a single ufunc call over whole arrays.
sum, mean, std, var, min, max, argmin, argmax, prod, cumsum, cumprod — all accept axis= and keepdims=. NaN-aware variants: nansum, nanmean, nanstd, nanmax. percentile / quantile with method= (the old interpolation= kwarg is removed in 2.x). np.unique (return_counts, return_inverse, return_index).
np.linalg.solve(A, b) for Ax = b — always prefer over inv(A) @ b (faster, more accurate). lstsq for over/underdetermined systems. eig (general), eigh (Hermitian/symmetric — faster, real eigenvalues). svd, qr, cholesky. det, matrix_rank, norm, pinv. @ operator and np.matmul for matrix multiplication. np.einsum for arbitrary tensor contractions with einsum_path for optimization.
np.random.default_rng(seed) returns a Generator. Methods: random, integers, normal, standard_normal, uniform, choice, permutation, shuffle. Parallel-safe streams via SeedSequence.spawn(n). The legacy global functions (np.random.seed, np.random.rand, np.random.randn, np.random.randint) still exist but should not be used in new code — Generator has better statistical properties and an explicit state.
np.save / np.load for .npy (single array, fast, typed). np.savez / np.savez_compressed for .npz (multi-array archive). np.loadtxt is fast for clean numeric text; np.genfromtxt handles missing values, names, mixed dtypes (slower). For real tabular data — delegate to pandas / polars parquet IO. np.memmap for arrays larger than RAM (file-backed, lazy paging).
Vectorize: replace Python for loops with whole-array ufuncs. Ensure contiguity: np.ascontiguousarray(arr) before BLAS-heavy work — non-contiguous strides force copies in C extensions. Use out= to avoid allocations in hot loops. np.einsum with optimize='optimal' for multi-tensor contractions. NumPy ufuncs and BLAS calls release the GIL — threading speeds up CPU-bound NumPy work despite the GIL. Profile with cProfile for call costs, line_profiler for line-level, memory_profiler for allocations.
Broadcasting rules (right-to-left dim match), np.broadcast_to, np.broadcast_shapes, common broadcasting errors and how to read them, silent-blow-up patterns
Vectorization principle, contiguity via ascontiguousarray, views vs copies for perf, np.einsumoptimize=True, profiling (cProfile / line_profiler), GIL release in C ops
Wrong vs right — Python loops over arrays, np.matrix, np.random.seed, removed aliases, .item() in hot loop, inv() instead of solve(), transposing without contiguity
