Claude Skill

run-nx-checks

Run nx format, lint, test, and build on affected or specified projects, then fix unambiguous failures

LLM Mart · 0 points · 12 views 0 listing impressions 0 install-command copies
Download eai-org-agent-toolkit-skills_run-nx-checks-3c808bf.zip · 7 KB

Install

skills CLI npx skills add https://github.com/eai-org/agent-toolkit/tree/main/skills/run-nx-checks
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install eai-org-agent-toolkit@llmmart
Git git clone https://github.com/eai-org/agent-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole eai-org/agent-toolkit collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Run Nx Checks

Run format, lint, typecheck, test, build. Fix unambiguous failures. Report anything judgment-laden and every file you changed.

Arguments

$ARGUMENTS — optional, space-separated: [cpuCount] [projectName] [--remote-cache]. Number token → cpuCount. Non-number, non-flag token → projectName. --remote-cache flag → opt back into the remote cache by dropping the remote-cache-off prefix. Default cpuCount = cores - 4 (min 1); count cores with node -p 'os.cpus().length'. Default project scope = affected. Default remote-cache state = off (see Steps).

$base, $cpuCount, $projectName and $snap in the commands below are placeholders: substitute their values (a fresh shell per Bash tool call holds none of them).

Workspace

Run nx commands from wherever nx.json lives in this repo (commonly the root; in some repos a subdirectory).

Setup (before step 1)

Keep the Nx daemon warm so the project graph is reused across targets:

NX_DAEMON=true npx nx daemon --start >/dev/null 2>&1 || true

Snapshot the dirty files, so the final report can name every file the run changes (hash-object without -w writes nothing); substitute the printed path for $snap there:

snap=$(mktemp -d "${TMPDIR:-/tmp}/nx-checks.XXXXXX") && git ls-files -z -mo --exclude-standard | while IFS= read -r -d '' f; do echo "$(git hash-object "$f" 2>/dev/null) $f"; done > "$snap/before.txt" && echo "snap=$snap"

Affected base

nx affected and format:write diff against the local default branch, which is often stale or missing. $projectName replaces only the affected commands, so resolve the base in both modes. NX_BASE set: skip this section and omit --base from every command below; Nx reads it and a deliberate env setting wins. Otherwise resolve the remote-tracking ref once and substitute the printed ref for $base in every affected, format:write and show projects --affected command below:

base=$(node -p 'const j=require("./nx.json"); j.defaultBase ?? j.affected?.defaultBase ?? "main"' 2>/dev/null || echo main)
base=${base#remotes/}; [[ $base == */* ]] || base="origin/$base"
GIT_TERMINAL_PROMPT=0 GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git fetch --quiet "${base%%/*}" "${base#*/}" || echo "fetch failed: base may be stale"
git rev-parse --verify --quiet "$base" >/dev/null && echo "base=$base" || echo "no such ref: omit --base"
  • Omit --base when the ref is missing (Nx falls back to defaultBase).
  • Never pass --head. With both flags Nx diffs two commits and ignores uncommitted and untracked files, so an agent's unstaged edits vanish and every check passes vacuously.
  • A failed fetch is not a failure: continue on the current ref, flag "base may be stale" in the final report, and never retry outside the sandbox for it.

Why: affected-base-rationale.md.

Fix rule

  • Apply only mechanical/unambiguous fixes: lint auto-fix output, missing imports/types, obvious type errors, test expectations that mirror a clear code change. An assertion or snapshot update is mechanical only when the failing expectation names a value the working-tree diff changed on purpose; edit that expectation by hand. Never pass -u/--updateSnapshot to a target.
  • Never guess on anything judgment-laden: test failure that could be a real bug vs. an outdated assertion, errors pointing at unrelated areas, pre-existing failures unrelated to recent work, anything where multiple plausible fixes exist. Running forked, you can't ask mid-run: leave such failures unfixed and carry them, with your analysis, into the final report.
  • Keep changes minimal and scoped to the failure. No drive-by refactors.
  • After fixing, re-run the same step command; the local cache replays the untouched projects. Repeat until clean or only judgment-laden failures remain.

Affected scope — sanity-check before step 1

Affected runs only (no $projectName); they can balloon. Before step 1, check scope with the graph-only npx nx show projects --affected --base=$base (fast, no build):

  • Sandbox .env false positives. The sandbox denies reading **/.env; nx affected hashes changed files, so an unreadable .env reads as changed and marks its project affected. Repos with .env-bearing apps (e.g. apps/*-api) thus drag those into every affected run and build them for nothing. Tell-tale: run git status; it prints <path>/.env: Operation not permitted for exactly those projects. Fix: add --exclude=<their project names> to every affected command (format:write takes none) and list them as excluded in the final report, naming any real edits they hold. Never re-run them outside the sandbox yourself; the user can, to include them.
  • Large fan-out. Large = more than half of npx nx show projects | wc -l or more than 20 projects, whichever is lower, counting affected projects after the .env exclusions (e.g. a widely-shared lib change rippling across the workspace). Don't build the world unprompted: skip steps 3–5 and report the project count and list in the final report so the user can re-run with $projectName.

Steps

Scope is mandatory — never narrow it yourself. With no $projectName argument, every target runs at full scope — nx affected for lint/typecheck/test/build, whole-changeset format:write. The single-project forms in the steps below apply only when the user explicitly passed $projectName. Never substitute nx run <proj>:<target>, nx <target> <changedLib>, or file-scoped format --files for the affected sweep: that skips every other affected project — exactly where a shared-lib change regresses (a dependent project whose tests import the changed lib).

Always prefix each task-running nx command (steps 1–5 and the flaky retry; daemon and show projects run no tasks) with the remote-cache-off env vars inline: NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache. NX_SKIP_REMOTE_CACHE turns off every remote cache on Nx 20.4 and later; the other two cover earlier versions and Powerpack. Unknown vars are no-ops, so the prefix is safe whatever remote-cache backend (if any) the repo uses.

The invariant: remote cache always off (unless the user passed --remote-cache), local cache always on — always disable, never autodetect (a passing shell-side auth check doesn't predict the in-process credential chain). Why: remote-cache-rationale.md.

If the user explicitly passed --remote-cache, drop the prefix. Expect pipeline hits on build (same --configuration) and typecheck; on test only in the single-project form and the flaky retry (the affected run's --maxWorkers=1 is a hashed override); never on lint (--fix) — keep the flags regardless.

Always keep the local cache on. The env vars above disable only the remote read-through cache; the local Nx cache must stay enabled so unchanged targets are replayed instead of re-run. Do not add --skip-nx-cache (nor NX_SKIP_NX_CACHE=true) to any command — it bypasses the local cache too, making every run slower for no benefit. The only valid reason to pass --skip-nx-cache is a specific, stated need to bypass the local cache — e.g. investigating a failure you suspect is caused by a stale cache entry. In that case, scope it to the single command under investigation and say why; never use it as the default.

Write the env vars literally at the start of each such command, exactly as in the steps below. Do not rely on export — each Bash tool call is a fresh shell, so exports do not carry across calls (true for any nx env var). Never stash the prefix in a shell variable (NX_OFF="…"; $NX_OFF npx nx … fails with "command not found": expanded variables are not parsed as assignments).

  1. Lint — NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t lint --base=$base --parallel=$cpuCount --fix (or NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx lint $projectName --fix).
  2. Format — NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx format:write --base=$base (both modes).
  3. Typecheck — NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t typecheck --base=$base --parallel=$cpuCount (or NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx typecheck $projectName --parallel=$cpuCount). Without the target, affected runs nothing and exits 0 and the single-project form errors with "cannot find configuration": report typecheck as n/a, never as failing.
  4. Test — NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t test --base=$base --parallel=$cpuCount --maxWorkers=1 (or NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx test $projectName).
  5. Build — NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t build --base=$base --configuration=production --parallel=$cpuCount (or NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx build $projectName --configuration=production --parallel=$cpuCount).

Apply the fix rule on any failure in steps 1–5 (a test failure: retry once first, see Flaky tests). A failure left unfixed never stops the run: carry on with the next step.

Flags per target

Why --configuration=production and --maxWorkers=1: flags-rationale.md.

  • --maxWorkers=1 on the test step only. Forwarding it to lint (ESLint) or build (esbuild) fails as an unknown option.
  • Affected/run-many only, not single-project. With one project there's no project-level fan-out, so capping to one worker just serializes it — let a single project use all cores.
  • Same reason, --parallel is dropped from single-project lint and test (one task each — no fan-out). It stays on single-project typecheck and build, because both fan out across the whole dependency chain: build has dependsOn: ["^build"] and the inferred typecheck dependsOn: ["^typecheck"].

Flaky tests — retry once to classify

A failed test target may be flaky, not a real break. On a test failure, re-run that one target once in step 4's single-project form, prefixed like the steps (… npx nx test <project>). If it then passes (or, with Nx Cloud on, Nx prints NX detected a flaky task), it's flaky — don't try to "fix" it; record it as a flaky project:target for the report. If it fails the same way again, treat it as real under the Fix rule.

Final report (mandatory)

This skill runs in a forked context, so its final message is the only channel back to the caller. End with:

  • the affected base used: the resolved ref, NX_BASE and its value, or omitted because the ref is missing; flag a failed fetch as possibly stale;
  • per target (lint / format / typecheck / test / build): clean, n/a, skipped (with the reason — for large fan-out, the project count and list; for .env false positives, the excluded projects), or each failing project:target with its cause, plus any flaky project:target;
  • every file the run changed: hand-fixed (from your own edits — file plus one line on what and why) and tool-applied (lint --fix, format:write — every other file that differs or is new when the Setup snapshot's git ls-files pipeline, not its mktemp, is re-run into $snap/after.txt and the two files are diffed; then rm -rf "$snap": a finished run leaves nothing in TMPDIR).

Never report a bare "checks passed": an unlisted failure, skipped target or unmentioned edit reads as green and the caller can't act on it.

Files (agent-toolkit)
  • affected-base-rationale.md 1.9 KB
    Loading…
  • flags-rationale.md 569 B
    Loading…
  • remote-cache-rationale.md 2.1 KB
    Loading…
  • SKILL.md 11.9 KB
    ---
    name: run-nx-checks
    description: Run nx format, lint, typecheck, test, and build on affected or specified projects, then fix unambiguous failures
    context: fork
    allowed-tools: Bash, Read, Edit, Write, Grep, Glob
    license: MIT
    metadata:
      version: "1.10"
    ---
    
    # Run Nx Checks
    
    Run format, lint, typecheck, test, build. Fix unambiguous failures. Report anything judgment-laden
    and every file you changed.
    
    ## Arguments
    
    `$ARGUMENTS` — optional, space-separated: `[cpuCount] [projectName] [--remote-cache]`. Number
    token → `cpuCount`. Non-number, non-flag token → `projectName`. `--remote-cache` flag → opt back
    into the remote cache by dropping the remote-cache-off prefix. Default `cpuCount` = cores - 4
    (min 1); count cores with `node -p 'os.cpus().length'`.
    Default project scope = affected. Default remote-cache state = off (see Steps).
    
    `$base`, `$cpuCount`, `$projectName` and `$snap` in the commands below are placeholders:
    substitute their values (a fresh shell per Bash tool call holds none of them).
    
    ## Workspace
    
    Run nx commands from wherever `nx.json` lives in this repo (commonly the root; in some repos a
    subdirectory).
    
    ## Setup (before step 1)
    
    Keep the Nx daemon warm so the project graph is reused across targets:
    
    ```bash
    NX_DAEMON=true npx nx daemon --start >/dev/null 2>&1 || true
    ```
    
    Snapshot the dirty files, so the final report can name every file the run changes (`hash-object`
    without `-w` writes nothing); substitute the printed path for `$snap` there:
    
    ```bash
    snap=$(mktemp -d "${TMPDIR:-/tmp}/nx-checks.XXXXXX") && git ls-files -z -mo --exclude-standard | while IFS= read -r -d '' f; do echo "$(git hash-object "$f" 2>/dev/null) $f"; done > "$snap/before.txt" && echo "snap=$snap"
    ```
    
    ### Affected base
    
    `nx affected` and `format:write` diff against the *local* default branch, which is often stale or
    missing. `$projectName` replaces only the `affected` commands, so resolve the base in both modes.
    `NX_BASE` set: skip this section and omit `--base` from every command below; Nx reads it and a
    deliberate env setting wins. Otherwise resolve the remote-tracking ref once and substitute the
    printed ref for `$base` in every `affected`, `format:write` and `show projects --affected` command
    below:
    
    ```bash
    base=$(node -p 'const j=require("./nx.json"); j.defaultBase ?? j.affected?.defaultBase ?? "main"' 2>/dev/null || echo main)
    base=${base#remotes/}; [[ $base == */* ]] || base="origin/$base"
    GIT_TERMINAL_PROMPT=0 GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git fetch --quiet "${base%%/*}" "${base#*/}" || echo "fetch failed: base may be stale"
    git rev-parse --verify --quiet "$base" >/dev/null && echo "base=$base" || echo "no such ref: omit --base"
    ```
    
    - Omit `--base` when the ref is missing (Nx falls back to `defaultBase`).
    - **Never pass `--head`.** With both flags Nx diffs two commits and ignores uncommitted and
      untracked files, so an agent's unstaged edits vanish and every check passes vacuously.
    - A failed fetch is not a failure: continue on the current ref, flag "base may be stale" in the
      final report, and never retry outside the sandbox for it.
    
    Why: [affected-base-rationale.md](affected-base-rationale.md).
    
    ## Fix rule
    
    - Apply only mechanical/unambiguous fixes: lint auto-fix output, missing imports/types, obvious type
      errors, test expectations that mirror a clear code change. An assertion or snapshot update is
      mechanical only when the failing expectation names a value the working-tree diff changed on
      purpose; edit that expectation by hand. Never pass `-u`/`--updateSnapshot` to a target.
    - Never guess on anything judgment-laden: test failure that could be a real bug vs. an outdated
      assertion, errors pointing at unrelated areas, pre-existing failures unrelated to recent work,
      anything where multiple plausible fixes exist. Running forked, you can't ask mid-run: leave such
      failures unfixed and carry them, with your analysis, into the final report.
    - Keep changes minimal and scoped to the failure. No drive-by refactors.
    - After fixing, re-run the same step command; the local cache replays the untouched projects.
      Repeat until clean or only judgment-laden failures remain.
    
    ## Affected scope — sanity-check before step 1
    
    Affected runs only (no `$projectName`); they can balloon. Before step 1, check scope with the
    graph-only `npx nx show projects --affected --base=$base` (fast, no build):
    
    - **Sandbox `.env` false positives.** The sandbox denies reading `**/.env`; `nx affected` hashes
      changed files, so an unreadable `.env` reads as *changed* and marks its project affected. Repos
      with `.env`-bearing apps (e.g. `apps/*-api`) thus drag those into every affected run and build
      them for nothing. Tell-tale: run `git status`; it prints `<path>/.env: Operation not permitted`
      for exactly those projects. Fix: add `--exclude=<their project names>` to every `affected`
      command (`format:write` takes none) and list them as excluded in the final report, naming any
      real edits they hold. Never re-run them outside the sandbox yourself; the user can, to include
      them.
    - **Large fan-out.** Large = more than half of `npx nx show projects | wc -l` or more than 20
      projects, whichever is lower, counting affected projects after the `.env` exclusions (e.g. a
      widely-shared lib change rippling across the workspace). Don't build the world unprompted: skip
      steps 3–5 and report the project count and list in the final report so the user can re-run with
      `$projectName`.
    
    ## Steps
    
    **Scope is mandatory — never narrow it yourself.** With no `$projectName` argument, *every* target
    runs at full scope — `nx affected` for lint/typecheck/test/build, whole-changeset `format:write`.
    The single-project forms in the steps below apply **only** when the user explicitly passed
    `$projectName`. Never substitute `nx run <proj>:<target>`, `nx <target> <changedLib>`, or
    file-scoped `format --files` for the affected sweep: that skips every other affected project —
    exactly where a shared-lib change regresses (a dependent project whose tests import the changed
    lib).
    
    Always prefix each task-running nx command (steps 1–5 and the flaky retry; `daemon` and
    `show projects` run no tasks) with the remote-cache-off env vars inline:
    `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache`.
    `NX_SKIP_REMOTE_CACHE` turns off every remote cache on Nx 20.4 and later; the other two cover
    earlier versions and Powerpack. Unknown vars are no-ops, so the prefix is safe whatever
    remote-cache backend (if any) the repo uses.
    
    The invariant: **remote cache always off (unless the user passed `--remote-cache`), local cache
    always on** — always disable, never autodetect (a passing shell-side auth check doesn't predict
    the in-process credential chain). Why: [remote-cache-rationale.md](remote-cache-rationale.md).
    
    If the user explicitly passed `--remote-cache`, drop the prefix. Expect pipeline hits on `build`
    (same `--configuration`) and `typecheck`; on `test` only in the single-project form and the flaky
    retry (the affected run's `--maxWorkers=1` is a hashed override); never on `lint` (`--fix`) — keep
    the flags regardless.
    
    **Always keep the local cache on.** The env vars above disable only the _remote_ read-through
    cache; the local Nx cache must stay enabled so unchanged targets are replayed instead of re-run.
    Do **not** add `--skip-nx-cache` (nor `NX_SKIP_NX_CACHE=true`) to any command — it bypasses the
    local cache too, making every run slower for no benefit. The only valid reason to pass
    `--skip-nx-cache` is a specific, stated need to bypass the local cache — e.g. investigating a
    failure you suspect is caused by a stale cache entry. In that case, scope it to the single command
    under investigation and say why; never use it as the default.
    
    Write the env vars literally at the start of each such command, exactly as in the steps below. Do
    **not** rely on `export` — each Bash tool call is a fresh shell, so exports do not carry across
    calls (true for any nx env var). Never stash the prefix in a shell variable
    (`NX_OFF="…"; $NX_OFF npx nx …` fails with "command not found": expanded variables are not parsed
    as assignments).
    
    1. Lint — `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t lint --base=$base --parallel=$cpuCount --fix`
       (or `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx lint $projectName --fix`).
    2. Format — `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx format:write --base=$base`
       (both modes).
    3. Typecheck — `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t typecheck --base=$base --parallel=$cpuCount`
       (or `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx typecheck $projectName --parallel=$cpuCount`).
       Without the target, `affected` runs nothing and exits 0 and the single-project form errors with
       "cannot find configuration": report typecheck as n/a, never as failing.
    4. Test — `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t test --base=$base --parallel=$cpuCount --maxWorkers=1`
       (or `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx test $projectName`).
    5. Build — `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx affected -t build --base=$base --configuration=production --parallel=$cpuCount`
       (or `NX_SKIP_REMOTE_CACHE=true NX_NO_CLOUD=true NX_POWERPACK_CACHE_MODE=no-cache npx nx build $projectName --configuration=production --parallel=$cpuCount`).
    
    Apply the fix rule on any failure in steps 1–5 (a test failure: retry once first, see Flaky
    tests). A failure left unfixed never stops the run: carry on with the next step.
    
    ### Flags per target
    
    Why `--configuration=production` and `--maxWorkers=1`: [flags-rationale.md](flags-rationale.md).
    
    - **`--maxWorkers=1` on the test step only.** Forwarding it to lint (ESLint) or build (esbuild)
      fails as an unknown option.
    - **Affected/run-many only, not single-project.** With one project there's no project-level
      fan-out, so capping to one worker just serializes it — let a single project use all cores.
    - Same reason, `--parallel` is dropped from single-project **lint** and **test** (one task each —
      no fan-out). It stays on single-project **typecheck** and **build**, because both fan out across
      the whole dependency chain: `build` has `dependsOn: ["^build"]` and the inferred `typecheck`
      `dependsOn: ["^typecheck"]`.
    
    ## Flaky tests — retry once to classify
    
    A failed `test` target may be flaky, not a real break. On a test failure, re-run that one target
    once in step 4's single-project form, prefixed like the steps (`… npx nx test <project>`). If it
    then passes (or, with Nx Cloud on, Nx prints `NX detected a flaky task`), it's flaky — don't try
    to "fix" it; record it as a flaky `project:target` for the report. If it fails the same way again,
    treat it as real under the Fix rule.
    
    ## Final report (mandatory)
    
    This skill runs in a forked context, so its final message is the only channel back to the caller.
    End with:
    
    - the affected base used: the resolved ref, `NX_BASE` and its value, or omitted because the ref is
      missing; flag a failed fetch as possibly stale;
    - per target (lint / format / typecheck / test / build): clean, n/a, skipped (with the reason —
      for large fan-out, the project count and list; for `.env` false positives, the excluded
      projects), or each failing `project:target` with its cause, plus any flaky `project:target`;
    - every file the run changed: hand-fixed (from your own edits — file plus one line on what and
      why) and tool-applied (lint `--fix`, `format:write` — every other file that differs or is new
      when the Setup snapshot's `git ls-files` pipeline, not its `mktemp`, is re-run into
      `$snap/after.txt` and the two files are diffed; then `rm -rf "$snap"`: a finished run leaves
      nothing in TMPDIR).
    
    Never report a bare "checks passed": an unlisted failure, skipped target or unmentioned edit reads
    as green and the caller can't act on it.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.