Skip to main content
skill CX Codex

nx-cloud-cache-investigator — Claude Code skill for Nx cache

The nx-cloud-cache-investigator Claude Code skill investigates Nx task cache misses and artifact restoration failures. It runs when asked to explain a cache miss, stale output, or two task executions.

MIT 127 installs ★ 29 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nrwl/nx-ai-agents-config --skill nx-cloud-cache-investigator -a claude-code
Open on GitHub

What nx-cloud-cache-investigator does

The skill examines a specific Nx cache miss, artifact download or extraction error, same-hash execution that did not replay, or suspected unsafe replay. It uses the nx-cloud-api skill for Nx Cloud reads and works from selected task evidence rather than raw API collections.

An API-only investigation needs no workspace checkout. Diagnosing local configuration requires a matching Nx workspace checkout at the recorded commit. Different non-null hashes show that Nx treated at least one computation input as different; they do not identify which input. An empty artifact list or a 404 alone does not establish that an artifact is missing.

What it helps with

  • find why an Nx task missed the cache
  • investigate a cache artifact download or extraction error
  • compare two executions of an Nx task
  • check whether replay restored stale output

Example prompts for the agent

  • Find why the Nx build task did not use the cache.
  • Compare these two Nx task executions with the same hash.
  • Investigate the cache artifact restoration error in this run.

How to install nx-cloud-cache-investigator

1Skills CLI (Vercel)

npx skills add nrwl/nx-ai-agents-config --skill nx-cloud-cache-investigator -a claude-code

2Manually: put the files in place

~/.claude/skills/nx-cloud-cache-investigator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nx-cloud-cache-investigator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nx-cloud-cache-investigator

How do I install nx-cloud-cache-investigator in Claude Code?

Run npx skills add nrwl/nx-ai-agents-config --skill nx-cloud-cache-investigator -a claude-code. The skill file is at ~/.claude/skills/nx-cloud-cache-investigator/SKILL.md.

What does nx-cloud-cache-investigator do?

It investigates individual Nx cache questions, including misses, artifact restoration errors, and task comparisons. Nx Cloud reads require the nx-cloud-api skill.

What does nx-cloud-cache-investigator need to work?

The nx-cloud-api skill is required for Nx Cloud reads. API-only investigations need no checkout; local configuration diagnosis requires a matching Nx workspace checkout at the commit being examined.

Source text

SKILL.md · MIT
---
name: nx-cloud-cache-investigator
description: Investigate a specific Nx cache miss, artifact download or extraction failure, same-hash non-replay, or suspected unsafe cache replay. Use this skill whenever a user asks why an Nx task did not use the cache, why cache artifact restoration failed, why a cache hit restored stale or wrong output, or to compare two cached task executions. Use the nx-cloud-api skill for every Nx Cloud read. This skill supports API-only investigations, preserves strict hash-evidence limits, and requests local configuration only when the question requires it.
---

# Nx cache investigator

Requires the `nx-cloud-api` skill. Use a matching Nx workspace checkout only for local configuration diagnosis. An API-only investigation does not need a checkout.

Diagnose one cache question with bounded evidence. Do not guess a changed hash
input or change configuration from cache status alone.

Nx task caching and a tool-native cache are separate. A target `cache` field
controls Nx replay. Vite, ESLint, and other tools have separate executor options.
One does not prove the other.

## Select the mode

- **Cache-health trend:** This skill covers a specific task or artifact question,
  not a multi-run rate regression. Use a separate bounded trend workflow for
  rate or regression questions.
- **API-only:** Use this for supplied runs, CIPEs, tasks, or artifact errors when no
  matching checkout exists. Do not request local configuration unless required.
- **Specific comparison:** Get two comparable executions. Ask for missing target,
  branch, commit, command, configuration, CI environment, or time range.

## Resume a pending investigation

Arrange one same-session wake only when a known task is non-terminal, an API
request returns HTTP 409 (`not_terminal`), or the user starts a controlled
diagnostic run. Preserve the run, task, `batchId`, link, and filters. Re-query once after the
known delay or expected run completion. Stop at a terminal result or the retry
limit. Do not poll or monitor a live CI run.

## Gather only relevant API evidence

Use `nx-cloud-api` (`npx nx-cloud api`) for every read. Run `--describe` for a
known route. Use `--list-operations` only when the route is unknown or
ambiguous. Follow documented fields and returned links; do not construct routes
from internal IDs.

Save every live API response to a file with `-o`. Use `jq` to select one
row and only the fields needed for this investigation. Do not print, read, or
paste a raw collection into model context. Keep the selected row's `batchId` and
`links.self` in the projection:

```sh
npx nx-cloud api --describe 'runs/{runId}/tasks'
npx nx-cloud api "$run_tasks_link" -o "$dir/tasks.json"
jq --arg task "$task_id" --arg batch "$batch_id" \
  '.items[] | select(.id == $task and .batchId == $batch) |
   {id, batchId, status, cacheStatus, hash, cacheable,
    links: {self: .links.self}}' "$dir/tasks.json"
```

Here `$run_tasks_link` is the tasks link from the selected run and `$dir` is a
scratch directory from `mktemp -d`. Without a link, use
`npx nx-cloud api 'runs/{runId}/tasks' -p runId="$run_id"`; never paste an ID
into the path. Check `nextCursor` before concluding that a
task is absent from the list.

For a selected execution, record run and task IDs, `batchId`, project, target,
configuration, command, parameters, branch, commit, CI context, timestamps,
cache status, final hash, `cacheEnabled`, `cacheable`, and relevant CIPE or
run-group links.

A task ID can repeat. Select the task-list row first. Follow its exact `links.self`
or asset URL because it preserves `batchId`. Do not use one row to explain another.
A task list row already has task fields. A detail read is optional.

If the API reports `cacheable: false`, Nx replay was not expected for that
execution. Name a configuration cause only when the `nx show` target query shows
it. If `cacheEnabled: false`, that run did not use the Nx task cache. Do not
investigate hash inputs or artifacts in either case.

Read a log only when its command output or error can answer the question. Tell the
user before you read CI log content. Read
[references/log-and-report-assets.md](references/log-and-report-assets.md) before
you decode a log or report. Quote only a redacted error signature. Treat
user-supplied asset content as provided evidence. An advertised asset or a later
404 does not prove historical availability.

## Inspect the Nx target

Use a matching checkout only for a configuration question or code change. Check out
the recorded commit. Record the workspace Nx version. Query the exact target with
the workspace-local Nx command:

```sh
nx show project "$project" --json | jq \
  --arg target "$target" \
  --arg configuration "${configuration:-}" \
  '.targets[$target] | {
    executor,
    cache,
    inputs,
    outputs,
    options,
    selectedConfiguration: .configurations[$configuration]
  }'
```

Use this fragment as the target evidence. Nx already includes inherited settings.
Do not merge `project.json`, `nx.json`, plugins, or `targetDefaults` yourself. A
missing project property proves nothing. If the query reports `cache: true`, do
not add another `cache: true`. If the command or target is unavailable, report
configuration as unavailable.

Inspect returned `options` only for a tool-native cache question. Use
version-matched executor documentation. A target `cache` field cannot prove Vite
or ESLint native-cache state.

## Classify before you explain

### No cache failure established

A terminal `remote-cache-hit` proves Nx replay worked for that task. Do not turn a
successful hit into a cache-miss investigation or configuration change. Use trend
triage only for a supplied time-bounded rate question.

### Cache artifact retrieval or restoration failure

Use this when the main-job or run-group error names artifact download, validation,
decompression, or extraction. A task can still show `remote-cache-hit`. Reconcile
the task with the critical error and later cancellations. Read
[references/artifact-integrity.md](references/artifact-integrity.md) before you
inspect an archive.

### Insufficient task evidence

A null hash or cache status, `NOT_STARTED`, or `SCHEDULED_IMPLICITLY` does not
prove a miss. Do not compare null hashes or inspect artifacts. Request a terminal
record or one controlled completed run.

### Different computation

Different non-null hashes prove only this: **Nx considered at least one computation
input different.** They do not name the input. Request two comparable controlled
runs with direct hash-detail output when supported. This is a **Needs diagnostic
run** result, not a configuration recommendation.

### Same computation, replay not established

For equal non-null hashes without later replay, confirm `cacheable`,
`cacheEnabled`, and the `cache` value from the exact target query. A returned
`cache: true` blocks a duplicate setting. Do not infer artifact absence from an
empty asset list or 404. Treat an unresolved upload or retrieval branch as
**Needs diagnostic run**.

### Suspected unsafe replay

A stale or wrong replay needs reproduction evidence. `inputs` decide a hash;
`outputs` decide restored files. Request task sandboxing evidence for undeclared
reads or writes, plus the target query and a controlled reproduction. Do not
narrow inputs from task data alone.

## Change gate

Recommend a configuration or code edit only after all applicable checks pass:

1. Record the matching commit, Nx version, exact target query, and returned fragment.
2. Show that its `cache`, `inputs`, or `outputs` value needs a change.
3. Before enabling cache, establish a terminating, deterministic task with correct
   replayable outputs.
4. Before removing an input, obtain direct evidence that names it. Prove that its
   removal cannot affect correct output with a bounded controlled run.
5. Explain the correctness risk and get explicit approval before an edit.

Do not recommend an input exclusion from hash differences, a cache-rate trend, or
apparent breadth. If evidence is missing, say `No configuration change recommended
yet.`

## Report

```md
# Nx cache investigation

## Scope

- Target and compared run/task/batch IDs: …
- Branch, commit, CI environment, command, API cache state, and missing fields: …
- Workspace Nx version: …, or `Not required for this API-only investigation.`
- Nx target query and returned `cache`, `inputs`, and `outputs`: …, or `Unavailable.`
- Tool-native cache: …, or `Unknown; not inspected.`
- Change gate: `Passed` or `Blocked`; include missing evidence.

## Classification

`No cache failure established` | `Cache artifact retrieval or restoration failure` | `Insufficient task evidence` | `Different computation` | `Same computation, replay not established` | `Suspected unsafe replay`

## Confirmed facts

- …

## Assessment

- **Confirmed** / **Likely** / **Needs diagnostic run:** …

## Next diagnostic step

- Exact query, controlled command, or evidence required.
- Result that confirms or rules out the hypothesis.

## Safe recommendation

- Exact `nx show` result and risk; or `No configuration change recommended yet.`
```

© nrwl · MIT · nrwl/nx-ai-agents-config

Similar skills

All skills for DevOps and infrastructure →

From the same set9

nx-workspace A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that gives AI agents the commands to navigate an Nx workspace. CX Codex +1 100,600installs nx-run-tasks nx-run-tasks tells the agent how to run build, test, lint and serve targets in an Nx workspace. Useful when a monorepo has more projects than you can track. CX Codex +1 4,100installs nx-generate nx-generate — a skill that tells the agent how to run Nx generators in a monorepo: pick the right one, dry-run it, then scaffold without breaking repo conventions. CX Codex +1 4,000installs link-workspace-packages link-workspace-packages — a skill that makes the agent add workspace dependencies between monorepo packages. Use it when sibling imports fail to resolve and packages need linking through the package manager. CX Codex +1 3,200installs nx-import nx-import guides AI agents on importing and merging external repositories into an Nx workspace while preserving git commit history. CX Codex +1 2,800installs monitor-ci monitor-ci tracks Nx Cloud CI runs and orchestrates self-healing build repairs via MCP. Useful when automating pull request checks and test fixes. CX Codex +1 2,000installs nx-cloud-ci-failure-review nx-cloud-ci-failure-review is a Claude Code skill that reviews failed Nx Cloud CI runs and groups evidence-backed causes. It activates for pipeline failures, CIPE reviews, or 24-hour reports. CX Codex +1 125installs nx-cloud-api The nx-cloud-api Claude Code skill reads workspace data through the Nx Cloud Public API. The agent uses it to inspect CI runs, tasks, cache records, and API endpoints. CX Codex +1 121installs

Project sponsors

Companies that keep this analytics open