Skip to content
Nx Workspace

Nx Workspace Skill

Nx's official read-only skill for exploring an Nx monorepo: list and filter projects, read fully resolved project and target configuration, and inspect nx.json and affected projects.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from nrwl/nx-ai-agents-config.

$ npx skills add nrwl/nx-ai-agents-config --skill nx-workspace

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/nx-workspace/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/nrwl/nx-ai-agents-config.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/nx-workspace ~/.claude/skills/nx-workspace

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/nx-workspace/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Lists and filters projects by glob, tag, directory, target, type or affected status
  • Reads fully resolved project config via nx show project --json, including inferred targets
  • Inspects target executors, options, inputs and outputs for caching
  • Reads nx.json targetDefaults, namedInputs, plugins and generators
  • Bundled reference for affected-project queries
  • Read-only; picks npx, pnpx or yarn from the lockfile

Nx Workspace is a skill published by Nrwl, the company behind the Nx build system, in its nx-ai-agents-config repository. It teaches a coding agent how to understand an Nx monorepo before acting on it: which projects exist, what targets they have, how they are configured and how they depend on each other. It is meant for answering questions about the workspace and for checking available targets when an nx command fails.

The key instruction is to ask Nx rather than read files. project.json holds only part of a project's configuration, because Nx plugins infer many targets, so the skill directs the agent to nx show project <name> --json (piped through jq) for the fully resolved targets, executors, options, inputs and outputs. It documents the project filter syntax shared by nx show projects, nx run-many and nx release: globs, tag: references, directories, negation, --withTarget, --type and --affected.

For workspace-level settings it reads nx.json directly (targetDefaults, namedInputs, plugins, generators) and points to the JSON schemas shipped in node_modules/nx. A bundled reference covers affected-project queries. The skill is strictly read-only and reminds the agent to prefix commands with npx, pnpx or yarn based on the workspace lockfile. MIT licensed.

SKILL.md

The instructions your agent loads, as published by Nx.

SKILL.md
name
nx-workspace
description
Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'.

Nx Workspace Exploration

This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies.

Keep in mind that you might have to prefix commands with npx/pnpx/yarn if nx isn't installed globally. Check the lockfile to determine the package manager in use.

Listing Projects

Use nx show projects to list projects in the workspace.

The project filtering syntax (-p/--projects) works across many Nx commands including nx run-many, nx release, nx show projects, and more. Filters support explicit names, glob patterns, tag references (e.g. tag:name), directories, and negation (e.g. !project-name).

# List all projects
nx show projects

# Filter by pattern (glob)
nx show projects --projects "apps/*"
nx show projects --projects "shared-*"

# Filter by tag
nx show projects --projects "tag:publishable"
nx show projects -p 'tag:publishable,!tag:internal'

# Filter by target (projects that have a specific target)
nx show projects --withTarget build

# Combine filters
nx show projects --type lib --withTarget test
nx show projects --affected --exclude="*-e2e"
nx show projects -p "tag:scope:client,packages/*"

# Negate patterns
nx show projects -p '!tag:private'
nx show projects -p '!*-e2e'

# Output as JSON
nx show projects --json
Project Configuration

Use nx show project <name> --json to get the full resolved configuration for a project.

Important: Do NOT read project.json directly - it only contains partial configuration. The nx show project --json command returns the full resolved config including inferred targets from plugins.

You can read the full project schema at node_modules/nx/schemas/project-schema.json to understand nx project configuration options.

# Get full project configuration
nx show project my-app --json

# Extract specific parts from the JSON
nx show project my-app --json | jq '.targets'
nx show project my-app --json | jq '.targets.build'
nx show project my-app --json | jq '.targets | keys'

# Check project metadata
nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}'
Target Information

Targets define what tasks can be run on a project.

# List all targets for a project
nx show project my-app --json | jq '.targets | keys'

# Get full target configuration
nx show project my-app --json | jq '.targets.build'

# Check target executor/command
nx show project my-app --json | jq '.targets.build.executor'
nx show project my-app --json | jq '.targets.build.command'

# View target options
nx show project my-app --json | jq '.targets.build.options'

# Check target inputs/outputs (for caching)
nx show project my-app --json | jq '.targets.build.inputs'
nx show project my-app --json | jq '.targets.build.outputs'

# Find projects with a specific target
nx show projects --withTarget serve
nx show projects --withTarget e2e
Workspace Configuration

Read nx.json directly for workspace-level configuration.
You can read the full project schema at node_modules/nx/schemas/nx-schema.json to understand nx project configuration options.

# Read the full nx.json
cat nx.json

# Or use jq for specific sections
cat nx.json | jq '.targetDefaults'
cat nx.json | jq '.namedInputs'
cat nx.json | jq '.plugins'
cat nx.json | jq '.generators'

Key nx.json sections:

  • targetDefaults - Default configuration applied to all targets of a given name
  • namedInputs - Reusable input definitions for caching
  • plugins - Nx plugins and their configuration
  • ...and much more, read the schema or nx.json for details
Affected Projects

If the user is asking about affected projects, read the [affected projects reference](references/AFFECTED.md) for detailed commands and examples.

Common Exploration Patterns
"What's in this workspace?"
nx show projects
nx show projects --type app
nx show projects --type lib
"How do I build/test/lint project X?"
nx show project X --json | jq '.targets | keys'
nx show project X --json | jq '.targets.build'
"What depends on library Y?"
# Use the project graph to find dependents
nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key'
Programmatic Answers

When processing nx CLI results, use command-line tools to compute the answer programmatically rather than counting or parsing output manually. Always use --json flags to get structured output that can be processed with jq, grep, or other tools you have installed locally.

Listing Projects
nx show projects --json

Example output:

["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"]

Common operations:

# Count projects
nx show projects --json | jq 'length'

# Filter by pattern
nx show projects --json | jq '.[] | select(startswith("shared-"))'

# Get affected projects as array
nx show projects --affected --json | jq '.'
Project Details
nx show project my-app --json

Example output:

{
  "root": "apps/my-app",
  "name": "my-app",
  "sourceRoot": "apps/my-app/src",
  "projectType": "application",
  "tags": ["type:app", "scope:client"],
  "targets": {
    "build": {
      "command": "vite build",
      "options": { "cwd": "apps/my-app" }
    },
    "serve": {
      "command": "vite",
      "options": { "cwd": "apps/my-app" }
    },
    "test": {
      "command": "vitest",
      "options": { "cwd": "apps/my-app" }
    }
  },
  "implicitDependencies": []
}

Common operations:

# Get target names
nx show project my-app --json | jq '.targets | keys'

# Get specific target config
nx show project my-app --json | jq '.targets.build'

# Get tags
nx show project my-app --json | jq '.tags'

# Get project root
nx show project my-app --json | jq -r '.root'
Project Graph
nx graph --print

Example output:

{
  "graph": {
    "nodes": {
      "my-app": {
        "name": "my-app",
        "type": "app",
        "data": { "root": "apps/my-app", "tags": ["type:app"] }
      },
      "shared-ui": {
        "name": "shared-ui",
        "type": "lib",
        "data": { "root": "libs/shared-ui", "tags": ["type:ui"] }
      }
    },
    "dependencies": {
      "my-app": [
        { "source": "my-app", "target": "shared-ui", "type": "static" }
      ],
      "shared-ui": []
    }
  }
}

Common operations:

# Get all project names from graph
nx graph --print | jq '.graph.nodes | keys'

# Find dependencies of a project
nx graph --print | jq '.graph.dependencies["my-app"]'

# Find projects that depend on a library
nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key'
Troubleshooting
"Cannot find configuration for task X:target"
# Check what targets exist on the project
nx show project X --json | jq '.targets | keys'

# Check if any projects have that target
nx show projects --withTarget target
"The workspace is out of sync"
nx sync
nx reset  # if sync doesn't fix stale cache
Install
New

The official Turborepo skill from the vercel/turborepo repo: points an agent at the docs bundled inside the installed turbo package, so turbo.json, caching, filtering and CI changes follow the exact version in use.

Featured

Build crash-safe AI agents on AgentKit and step.ai — durable tool calls, human-in-the-loop approval, realtime progress, and when not to reach for an agent loop at all.

Featured

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

New

Prisma's official command reference for Prisma ORM 7: init, generate, migrate, db, dev, studio and mcp, with a safety checkpoint before destructive commands.

Browse all skills →