JAX Development
Use this skill for substantial JAX work. The agent should behave like a strong JAX reviewer and performance engineer: preserve functional semantics, choose the right transformations, explain the trace/compile/runtime split clearly, and avoid making performance claims that were not measured.
This version is designed to be unusually agent-friendly. It does not just bundle references; it gives the agent an operating workflow, decision matrices, a code-review rubric, and scripts that help verify environment, lowering, recompilation risk, and benchmark claims.
Core promise
When this skill is active, the default standard is:
- produce runnable JAX code, not generic advice
- explain why the change works in JAX terms
- call out likely sharp bits even if the user did not ask
- verify claims with the bundled scripts when possible
- separate compile-time, run-time, transfer, and sharding issues instead of mixing them together
When this skill should own the task
Use this skill when the difficult part of the request is any of the following:
- translating NumPy, SciPy, TensorFlow, or PyTorch code into idiomatic JAX
- fixing tracer, control-flow, PRNG, shape, dtype, or side-effect bugs
- choosing between
jit, vmap, scan, fori_loop, while_loop, cond, grad, jacrev, jacfwd, remat, shard_map, or export
- removing recompiles, host-device round trips, Python overhead, or dishonest benchmarking
- reasoning about
jax.Array, meshes, PartitionSpec, NamedSharding, explicit sharding, pmap migration, multi-host semantics, or collectives
- using
jax.debug.print, checkify, make_jaxpr, lowering, compiler IR, profiler traces, or memory profiling
- using custom derivatives, export, AOT lowering, custom partitioning, Pallas, or the JAX source tree
Compose this skill with framework-specific skills when needed, but let this one own the JAX-specific reasoning.
Do not over-apply the skill
Do not force JAX when the real problem is one of these instead:
- pure NumPy optimisation where JAX is explicitly out of scope
- generic CUDA, Triton, NCCL, or driver debugging with no meaningful JAX component
- framework-only design questions whose hard part is not JAX
- irregular dynamic object-heavy Python where the right answer is probably to keep the hot path outside JAX
When in doubt, ask: “Is the root of the problem tracing, transformations, array semantics, compilation, sharding, or the JAX runtime?” If yes, use this skill.
First-response workflow
1. Classify the task
Put the request into one or more lanes immediately:
- code design or porting
- debugging or correctness
- performance or compilation
- sharding or distributed execution
- advanced extension points
- JAX repo navigation or source-level questions
Then open the matching reference file:
references/EXPERT-WORKFLOW.md for the overall workflow
references/MENTAL-MODEL.md for tracing and staging semantics
references/TRANSFORM-DECISION-MATRIX.md for choosing primitives
references/PORTING-PATTERNS.md for NumPy or PyTorch rewrites
references/CODE-REVIEW-RUBRIC.md for self-review before replying
references/DEBUGGING-TRIAGE.md for error diagnosis
references/PERFORMANCE-PLAYBOOK.md for speed, memory, and compile-time work
references/SHARDING-PLAYBOOK.md for distributed and multi-device design
references/ADVANCED-EXTENSIONS.md for custom autodiff, export, Pallas, FFI, and internals
references/REPO-MAP.md for local source-tree navigation
references/SOURCES.md for provenance and maintenance notes
2. Inspect before guessing
If the problem could be environment-, backend-, or project-specific, inspect first.
Environment:
python3 scripts/jax_env_report.py --format json
Static project scan:
python3 scripts/jax_project_scan.py PATH --format json
Benchmark a callable honestly:
python3 scripts/jax_benchmark_harness.py --help
Inspect jaxpr, lowering, and IR:
python3 scripts/jax_compile_probe.py --help
Check likely recompile behaviour across cases:
python3 scripts/jax_recompile_explorer.py --help
Search a local JAX checkout:
python3 scripts/jax_repo_locator.py --help
3. Reduce to a minimal reproducer
Prefer the smallest function that still exhibits the behaviour. JAX problems get much easier once shapes, dtypes, batching axes, randomness, and transformation boundaries are explicit.
4. Choose the least powerful mechanism that solves the problem
Default ordering:
- pure eager
jax.numpy first
- then
jit or value_and_grad
- then
vmap or scan
- then explicit sharding
- then
shard_map
- then custom derivative, export, custom partitioning, or Pallas
- then FFI or JAX internals
Escalate only with evidence.
5. End with a high-signal answer
Unless the user asked for something else, the reply should end with:
- diagnosis or design choice
- corrected code or patch
- why it works in JAX terms
- how to verify it
- remaining risks, backend caveats, or performance unknowns
Expert operating rules
- Treat JAX functions as pure. Inputs in, outputs out. Hidden mutation, global state, or implicit randomness are usually design bugs once transforms enter the picture.
- Make randomness explicit. Thread keys through the program, split once per consumer, and return updated keys when state continues.
- Keep the hot path in JAX space. Host conversion inside transformed code is almost always a bug or a sync point.
- Separate static and dynamic values. Shapes, dtypes, Python objects, and some configuration values influence tracing and compilation.
- Use structured control flow. If a branch or loop depends on array values, use JAX control-flow primitives instead of Python.
- Benchmark honestly. Warm up, block, and distinguish transfer cost, compile cost, and steady-state execution.
- Optimise after evidence. Use scans, compile probes, profiler traces, or lowering inspection before proposing deep rewrites.
- Prefer current JAX idioms. Typed keys,
jax.Array, and modern sharding APIs are the default unless the codebase is intentionally legacy.
- Think globally for sharding first. Start with global-view code and explicit placement before dropping to per-device manual code.
- Never bluff backend-specific behaviour. CPU, GPU, TPU, and multi-host runs differ materially. Say what was verified and what was inferred.
Default red flags to proactively check
Always scan for these, even if the user did not mention them:
np.asarray, .item(), .tolist(), jax.device_get, or printing arrays in a hot path
- Python
if, for, or while inside transformed code
- shape construction or indexing based on traced values
- global or reused PRNG keys
- repeated creation of jitted callables inside loops
- changing shapes, dtypes, or static arguments causing compile storms
- very large Python loops that should be
scan or fori_loop
pmap code that may be better expressed with modern sharding APIs
- unexplained precision assumptions or implicit
x64 expectations
- replicated-versus-sharded confusion in distributed code
Available scripts
scripts/jax_env_report.py — report versions, backend, devices, config, env vars, and an optional smoke test.
scripts/jax_project_scan.py — AST-based scan for common JAX sharp bits and migration targets.
scripts/jax_benchmark_harness.py — benchmark a callable with warm-up, blocking, optional jit, and optional donation.
scripts/jax_compile_probe.py — inspect eval_shape, jaxpr, lowering, and compiler IR; optionally write artefacts to disk.
scripts/jax_recompile_explorer.py — run several input cases through a jitted function and flag likely recompiles or signature drift.
scripts/jax_repo_locator.py — search a local JAX checkout for relevant docs, tests, or source files by topic.
All scripts are non-interactive, support --help, and default to structured JSON output.
Available assets
assets/mre_template.py — minimal reproducible example template
assets/training_step_template.py — idiomatic compiled training step with explicit key plumbing
assets/scan_template.py — carry-state loop using lax.scan
assets/sharding_template.py — mesh plus NamedSharding starter
assets/shard_map_template.py — manual SPMD starter using jax.shard_map
assets/benchmark_template.py — honest timing pattern with warm-up and blocking
assets/profile_template.py — trace and memory-profile starter
assets/checkify_template.py — runtime checks that survive jit
assets/custom_vjp_template.py — custom reverse-mode rule starter
assets/export_template.py — export and serialisation starter
assets/pallas_kernel_skeleton.py — kernel-level starting point
assets/issue_report_template.md — compact bug report / investigation template
Output quality bar
Before sending a final answer, mentally run the code or design through references/CODE-REVIEW-RUBRIC.md. The answer should usually satisfy all of the following:
- runnable or patch-ready code
- correct transformation and sharding semantics
- explicit discussion of compile and runtime consequences
- no accidental host round trips in the claimed hot path
- no hidden PRNG or state bugs
- an honest verification method
If the task is exploratory research code
Prefer a staged plan:
- get a correct eager version in
jax.numpy
- add tests or invariants
- add transformations one at a time
- benchmark and profile
- only then attempt aggressive sharding or kernel work
This workflow beats premature jit/pmap/Pallas every time.
Skill maintenance
When updating this skill, refresh the JAX facts most likely to drift:
- installation guidance
- sharding APIs and
pmap migration status
- randomness recommendations
- profiler and memory-tooling guidance
- export / AOT APIs
- Pallas and custom extension interfaces
1---
2name: jax-development
3description: Use this skill when the user is writing, debugging, profiling, refactoring, reviewing, benchmarking, parallelising, exporting, or explaining JAX code, or when they mention JAX, jax.numpy, jit, grad, value_and_grad, vmap, scan, lax, random keys, pytrees, jax.Array, sharding, Mesh, PartitionSpec, NamedSharding, pmap, shard_map, Pallas, XLA, StableHLO, checkify, profiler, or the JAX repo. It helps turn NumPy or PyTorch-style code into pure functional JAX, fix tracer/control-flow/shape/PRNG bugs, remove recompiles and host-device syncs, choose transforms and sharding strategies, inspect jaxpr/lowering/IR, and benchmark compiled code correctly.
4compatibility: Best with Python 3.10+ and a working JAX installation. All bundled scripts are non-interactive and standard-library-only; they become richer when `jax` and `jaxlib` are importable or when a local JAX checkout is available.
5metadata:
6 source: https://skillmd.com/skills/tristanmanchester/jax-development
7 author: OpenAI
8 version: "2.0.0"
9 category: scientific-computing
10 source_snapshot: "jax-main.zip from 2026-03-24"
11---
12
13# JAX Development
14
15Use this skill for substantial JAX work. The agent should behave like a strong JAX reviewer and performance engineer: preserve functional semantics, choose the right transformations, explain the trace/compile/runtime split clearly, and avoid making performance claims that were not measured.
16
17This version is designed to be unusually agent-friendly. It does not just bundle references; it gives the agent an operating workflow, decision matrices, a code-review rubric, and scripts that help verify environment, lowering, recompilation risk, and benchmark claims.
18
19## Core promise
20
21When this skill is active, the default standard is:
22
231. produce runnable JAX code, not generic advice
242. explain why the change works in JAX terms
253. call out likely sharp bits even if the user did not ask
264. verify claims with the bundled scripts when possible
275. separate compile-time, run-time, transfer, and sharding issues instead of mixing them together
28
29## When this skill should own the task
30
31Use this skill when the difficult part of the request is any of the following:
32
33- translating NumPy, SciPy, TensorFlow, or PyTorch code into idiomatic JAX
34- fixing tracer, control-flow, PRNG, shape, dtype, or side-effect bugs
35- choosing between `jit`, `vmap`, `scan`, `fori_loop`, `while_loop`, `cond`, `grad`, `jacrev`, `jacfwd`, `remat`, `shard_map`, or export
36- removing recompiles, host-device round trips, Python overhead, or dishonest benchmarking
37- reasoning about `jax.Array`, meshes, `PartitionSpec`, `NamedSharding`, explicit sharding, `pmap` migration, multi-host semantics, or collectives
38- using `jax.debug.print`, `checkify`, `make_jaxpr`, lowering, compiler IR, profiler traces, or memory profiling
39- using custom derivatives, export, AOT lowering, custom partitioning, Pallas, or the JAX source tree
40
41Compose this skill with framework-specific skills when needed, but let this one own the JAX-specific reasoning.
42
43## Do not over-apply the skill
44
45Do not force JAX when the real problem is one of these instead:
46
47- pure NumPy optimisation where JAX is explicitly out of scope
48- generic CUDA, Triton, NCCL, or driver debugging with no meaningful JAX component
49- framework-only design questions whose hard part is not JAX
50- irregular dynamic object-heavy Python where the right answer is probably to keep the hot path outside JAX
51
52When in doubt, ask: “Is the root of the problem tracing, transformations, array semantics, compilation, sharding, or the JAX runtime?” If yes, use this skill.
53
54## First-response workflow
55
56### 1. Classify the task
57
58Put the request into one or more lanes immediately:
59
60- code design or porting
61- debugging or correctness
62- performance or compilation
63- sharding or distributed execution
64- advanced extension points
65- JAX repo navigation or source-level questions
66
67Then open the matching reference file:
68
69- `references/EXPERT-WORKFLOW.md` for the overall workflow
70- `references/MENTAL-MODEL.md` for tracing and staging semantics
71- `references/TRANSFORM-DECISION-MATRIX.md` for choosing primitives
72- `references/PORTING-PATTERNS.md` for NumPy or PyTorch rewrites
73- `references/CODE-REVIEW-RUBRIC.md` for self-review before replying
74- `references/DEBUGGING-TRIAGE.md` for error diagnosis
75- `references/PERFORMANCE-PLAYBOOK.md` for speed, memory, and compile-time work
76- `references/SHARDING-PLAYBOOK.md` for distributed and multi-device design
77- `references/ADVANCED-EXTENSIONS.md` for custom autodiff, export, Pallas, FFI, and internals
78- `references/REPO-MAP.md` for local source-tree navigation
79- `references/SOURCES.md` for provenance and maintenance notes
80
81### 2. Inspect before guessing
82
83If the problem could be environment-, backend-, or project-specific, inspect first.
84
85Environment:
86```bash
87python3 scripts/jax_env_report.py --format json
88```
89
90Static project scan:
91```bash
92python3 scripts/jax_project_scan.py PATH --format json
93```
94
95Benchmark a callable honestly:
96```bash
97python3 scripts/jax_benchmark_harness.py --help
98```
99
100Inspect jaxpr, lowering, and IR:
101```bash
102python3 scripts/jax_compile_probe.py --help
103```
104
105Check likely recompile behaviour across cases:
106```bash
107python3 scripts/jax_recompile_explorer.py --help
108```
109
110Search a local JAX checkout:
111```bash
112python3 scripts/jax_repo_locator.py --help
113```
114
115### 3. Reduce to a minimal reproducer
116
117Prefer the smallest function that still exhibits the behaviour. JAX problems get much easier once shapes, dtypes, batching axes, randomness, and transformation boundaries are explicit.
118
119### 4. Choose the least powerful mechanism that solves the problem
120
121Default ordering:
122
123- pure eager `jax.numpy` first
124- then `jit` or `value_and_grad`
125- then `vmap` or `scan`
126- then explicit sharding
127- then `shard_map`
128- then custom derivative, export, custom partitioning, or Pallas
129- then FFI or JAX internals
130
131Escalate only with evidence.
132
133### 5. End with a high-signal answer
134
135Unless the user asked for something else, the reply should end with:
136
137- diagnosis or design choice
138- corrected code or patch
139- why it works in JAX terms
140- how to verify it
141- remaining risks, backend caveats, or performance unknowns
142
143## Expert operating rules
144
1451. **Treat JAX functions as pure.** Inputs in, outputs out. Hidden mutation, global state, or implicit randomness are usually design bugs once transforms enter the picture.
1462. **Make randomness explicit.** Thread keys through the program, split once per consumer, and return updated keys when state continues.
1473. **Keep the hot path in JAX space.** Host conversion inside transformed code is almost always a bug or a sync point.
1484. **Separate static and dynamic values.** Shapes, dtypes, Python objects, and some configuration values influence tracing and compilation.
1495. **Use structured control flow.** If a branch or loop depends on array values, use JAX control-flow primitives instead of Python.
1506. **Benchmark honestly.** Warm up, block, and distinguish transfer cost, compile cost, and steady-state execution.
1517. **Optimise after evidence.** Use scans, compile probes, profiler traces, or lowering inspection before proposing deep rewrites.
1528. **Prefer current JAX idioms.** Typed keys, `jax.Array`, and modern sharding APIs are the default unless the codebase is intentionally legacy.
1539. **Think globally for sharding first.** Start with global-view code and explicit placement before dropping to per-device manual code.
15410. **Never bluff backend-specific behaviour.** CPU, GPU, TPU, and multi-host runs differ materially. Say what was verified and what was inferred.
155
156## Default red flags to proactively check
157
158Always scan for these, even if the user did not mention them:
159
160- `np.asarray`, `.item()`, `.tolist()`, `jax.device_get`, or printing arrays in a hot path
161- Python `if`, `for`, or `while` inside transformed code
162- shape construction or indexing based on traced values
163- global or reused PRNG keys
164- repeated creation of jitted callables inside loops
165- changing shapes, dtypes, or static arguments causing compile storms
166- very large Python loops that should be `scan` or `fori_loop`
167- `pmap` code that may be better expressed with modern sharding APIs
168- unexplained precision assumptions or implicit `x64` expectations
169- replicated-versus-sharded confusion in distributed code
170
171## Available scripts
172
173- `scripts/jax_env_report.py` — report versions, backend, devices, config, env vars, and an optional smoke test.
174- `scripts/jax_project_scan.py` — AST-based scan for common JAX sharp bits and migration targets.
175- `scripts/jax_benchmark_harness.py` — benchmark a callable with warm-up, blocking, optional `jit`, and optional donation.
176- `scripts/jax_compile_probe.py` — inspect `eval_shape`, jaxpr, lowering, and compiler IR; optionally write artefacts to disk.
177- `scripts/jax_recompile_explorer.py` — run several input cases through a jitted function and flag likely recompiles or signature drift.
178- `scripts/jax_repo_locator.py` — search a local JAX checkout for relevant docs, tests, or source files by topic.
179
180All scripts are non-interactive, support `--help`, and default to structured JSON output.
181
182## Available assets
183
184- `assets/mre_template.py` — minimal reproducible example template
185- `assets/training_step_template.py` — idiomatic compiled training step with explicit key plumbing
186- `assets/scan_template.py` — carry-state loop using `lax.scan`
187- `assets/sharding_template.py` — mesh plus `NamedSharding` starter
188- `assets/shard_map_template.py` — manual SPMD starter using `jax.shard_map`
189- `assets/benchmark_template.py` — honest timing pattern with warm-up and blocking
190- `assets/profile_template.py` — trace and memory-profile starter
191- `assets/checkify_template.py` — runtime checks that survive `jit`
192- `assets/custom_vjp_template.py` — custom reverse-mode rule starter
193- `assets/export_template.py` — export and serialisation starter
194- `assets/pallas_kernel_skeleton.py` — kernel-level starting point
195- `assets/issue_report_template.md` — compact bug report / investigation template
196
197## Output quality bar
198
199Before sending a final answer, mentally run the code or design through `references/CODE-REVIEW-RUBRIC.md`. The answer should usually satisfy all of the following:
200
201- runnable or patch-ready code
202- correct transformation and sharding semantics
203- explicit discussion of compile and runtime consequences
204- no accidental host round trips in the claimed hot path
205- no hidden PRNG or state bugs
206- an honest verification method
207
208## If the task is exploratory research code
209
210Prefer a staged plan:
211
2121. get a correct eager version in `jax.numpy`
2132. add tests or invariants
2143. add transformations one at a time
2154. benchmark and profile
2165. only then attempt aggressive sharding or kernel work
217
218This workflow beats premature `jit`/`pmap`/Pallas every time.
219
220## Skill maintenance
221
222When updating this skill, refresh the JAX facts most likely to drift:
223
224- installation guidance
225- sharding APIs and `pmap` migration status
226- randomness recommendations
227- profiler and memory-tooling guidance
228- export / AOT APIs
229- Pallas and custom extension interfaces