# Awkward Array

> Guidance for working with Awkward Array 2.0 jagged arrays and records in Python. Use when building or debugging `awkward` workflows, including record construction with `ak.zip`, adding fields with `ak.with_field`, filtering/aggregation, combinatorics (`ak.cartesian`/`ak.combinations`), `argmin`/`argmax` slicing, flattening, sorting, and NumPy interop or common Awkward pitfalls.

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

---


# Awkward Array

## Overview

Use this skill to apply Awkward 2.0 best practices for jagged arrays, especially in HEP-style event data models. Keep guidance lean in this file and load reference notes only when needed.

## Core workflow

1. Build an event data model (records) with `ak.zip`.
2. Filter early at the event level.
3. Perform combinatorics or derived calculations.
4. Add derived fields back into the record with `ak.with_field`.
5. Repeat until the final values are present in the EDM.

## Reference guide

Load only the reference files that matches the task:

- `references/best-practices.md`: use when setting overall approach or reminding about Awkward 2.0 usage and axes.
- `references/records.md`: use when building records or adding fields.
- `references/filtering-aggregation.md`: use for boolean masking, `ak.sum`/`ak.count`/`ak.num`, and axis guidance.
- `references/sorting.md`: use for `ak.sort`.
- `references/combinatorics.md`: use for pairings or n-way combinations (`ak.cartesian`, `ak.combinations`).
- `references/argmin-argmax.md`: use when selecting min/max elements in jagged lists.
- `references/flattening.md`: use for `ak.flatten` behavior and axis rules.
- `references/numpy-interop.md`: use when mixing NumPy operations with Awkward arrays.
- `references/pitfalls.md`: use for common API mistakes and missing functions.
- `references/awkward-files.md`: use for file I/O patterns (read/write) with Awkward arrays.

## Constraints

- Use Awkward 2.0 APIs and syntax only.
- Avoid `axis=None` unless the function explicitly supports it.
- Ensure `awkward` is listed as a dependency in the active environment (venv plus `pyproject.toml` or `requirements.txt`).