nx-workspace-patterns

Overview of nx-workspace-patterns skill

What nx-workspace-patterns solves

The nx-workspace-patterns skill helps you design or clean up an Nx monorepo with practical structure decisions, not just generic “use Nx” advice. It is most useful when you need a clear workspace layout, enforceable project boundaries, better affected-command behavior in CI, or a sensible library taxonomy for long-term scale.

Best fit readers

This skill is best for engineers, tech leads, and AI-assisted repo maintainers who are:

• starting a new Nx workspace
• migrating an existing monorepo to Nx
• trying to reduce cross-project coupling
• improving build performance with caching and affected runs
• deciding how to split apps, libs, and shared code

Real job-to-be-done

Most users do not need a theory lesson on Nx. They need a repeatable pattern for apps/, libs/, tools/, nx.json, and project boundaries that matches their repo size, team structure, and CI needs. nx-workspace-patterns is valuable because it turns a vague goal like “set up Nx correctly” into a concrete workspace shape and naming model.

What makes this skill different

The strongest differentiator in nx-workspace-patterns is that it focuses on production workspace patterns:

• architectural layout for monorepos
• library type conventions such as feature, ui, data-access, util, and shell
• boundary-conscious organization
• CI-oriented Nx usage like affected commands and caching

That makes it more decision-oriented than a generic prompt asking an AI to “suggest an Nx structure.”

What to know before installing

This is a guidance skill, not an automation package. It does not ship helper scripts, generators, or reference assets in this repository path. Its value is the structured patterns in SKILL.md, so adoption depends on whether you want architecture guidance you can adapt, not a turnkey toolchain.

How to Use nx-workspace-patterns skill

Install context for nx-workspace-patterns

Use this skill inside an agent or AI workflow that supports GitHub-hosted skills. If your environment uses the common Skills install flow, add the repository and then invoke nx-workspace-patterns when you want help with Nx workspace design, migration, or optimization.

A common install pattern is:

npx skills add https://github.com/wshobson/agents

Then call the nx-workspace-patterns skill by name from your AI workflow.

Read this file first

Start with:

• plugins/developer-essentials/skills/nx-workspace-patterns/SKILL.md

There are no extra resources/, rules/, or helper scripts in this skill folder, so most of the usable guidance is concentrated in that single file.

What input the skill needs

nx-workspace-patterns works best when you give it repository-specific constraints instead of asking for a generic Nx example. Useful inputs include:

• current repo type: polyrepo, monorepo, or partial migration
• frontend/backend stack
• number of apps and shared packages
• team ownership boundaries
• current pain points: slow CI, circular deps, unclear shared code, weak caching
• target state: faster affected runs, stricter boundaries, easier code reuse

Turn a rough goal into a strong prompt

Weak prompt:

Help me use Nx.

Better prompt:

Use nx-workspace-patterns to propose an Nx workspace for 3 apps (web, admin, api) and shared libraries. We want strict boundaries, affected-based CI, and remote caching. Suggest folder structure, library types, naming conventions, and example nx.json defaults.

Best prompt:

Use nx-workspace-patterns for Project Setup. We are migrating a TypeScript monorepo with React apps and a Node API into Nx. Current issues: shared code is mixed together, CI runs everything, and teams accidentally import across domains. Propose:

1. workspace layout for apps/, libs/, and tools/
2. a library taxonomy using feature, ui, data-access, util, shell
3. tagging and boundary rules
4. affected-command CI workflow
5. remote cache rollout steps
6. migration order with low-risk first moves

The stronger version gives the skill enough context to produce architecture you can actually implement.

Best workflow in practice

A high-signal way to use the nx-workspace-patterns skill:

1. describe your current repo and pains
2. ask for a proposed target workspace shape
3. ask for dependency boundary rules and naming conventions
4. ask for CI commands using affected runs
5. review the output against your real deployment and team ownership model
6. ask for a phased migration plan instead of a big-bang rewrite

This workflow matters because Nx decisions compound. A pretty folder tree without dependency rules or CI strategy is usually not enough.

Patterns the skill is especially good at

The source content is strongest on:

• Nx architecture layout
• app/lib separation
• library type classification
• project boundary thinking
• CI optimization direction using affected commands
• remote caching as an operational concern

If that is your decision surface, nx-workspace-patterns usage is much more valuable than a generic monorepo prompt.

Repository files and concepts to map first

Before applying the skill to your repo, map these items:

• deployable apps
• reusable shared code
• domain-specific business logic
• API and state management layers
• utility-only modules
• custom tooling candidates under tools/

That makes the library type model from nx-workspace-patterns much easier to apply cleanly.

How to use the library type model well

The skill’s library taxonomy is one of its most useful parts:

• feature: business logic and smart components
• ui: presentational pieces
• data-access: API and state integration
• util: pure helpers
• shell: app composition and bootstrapping

Do not use these labels as decoration. Use them to restrict imports. For example, ui should usually stay light and reusable, while feature code should not become a dumping ground for unrelated shared helpers.

When nx-workspace-patterns helps most with CI

If your Nx adoption goal is faster CI, ask the skill for:

• affected command strategy
• cacheable target suggestions
• task defaults in nx.json
• remote caching rollout order
• dependency boundary cleanup before performance tuning

This avoids a common mistake: trying to optimize caching before the workspace graph is stable.

Misfit cases

Do not expect nx-workspace-patterns install to replace:

• official Nx package installation docs
• framework-specific generators
• executor/plugin selection guidance in depth
• exact version-by-version migration commands

If you need package compatibility matrices or plugin-specific setup, combine this skill with the official Nx docs.

nx-workspace-patterns skill FAQ

Is nx-workspace-patterns good for beginners?

Yes, if you already know what a monorepo is and need help making structural decisions. It is less useful for absolute beginners who first need Nx basics like CLI setup, generators, and target execution.

Is this better than a normal AI prompt?

Usually yes for architecture work. The nx-workspace-patterns skill gives the model a more opinionated structure around workspace layout, library roles, and CI-oriented design. A normal prompt often returns generic folders without clear dependency intent.

Does it help with migration or only greenfield setup?

Both. It is especially helpful for migration planning because it gives you a target taxonomy and boundary model. For migrations, ask for phased moves, temporary compatibility rules, and low-risk first refactors.

What does nx-workspace-patterns not cover deeply?

It does not appear to include extra supporting files for:

• automated validation
• custom scripts
• generator code
• organization-specific rule packs

So treat it as a pattern guide, not a complete Nx platform kit.

Is nx-workspace-patterns for Project Setup only?

No. nx-workspace-patterns for Project Setup is a strong use case, but it also helps when tightening boundaries, reorganizing libraries, introducing caching, or improving affected-based CI after the workspace already exists.

Should I use this if I only have one small app?

Probably not yet. If you have a single small app with little shared code, Nx structure can be more overhead than benefit. This skill becomes more valuable once you have multiple apps, growing shared code, or cross-team ownership concerns.

How to Improve nx-workspace-patterns skill

Give concrete repo constraints up front

The fastest way to improve nx-workspace-patterns output quality is to provide:

• app count
• tech stack
• ownership boundaries
• current dependency problems
• CI pain points
• desired migration speed

Without that, the skill can only return a generic workspace template.

Ask for boundary rules, not just folders

A common failure mode is accepting a clean directory tree with no enforceable architecture. Push the skill to define:

• allowed import directions
• tagging strategy
• examples of forbidden dependencies
• where cross-cutting utilities should live

That turns nx-workspace-patterns usage into something you can operationalize.

Provide examples of messy code placement

If your current repo has unclear shared code, give 5 to 10 real modules and ask where each should move:

• auth hooks
• API clients
• formatting helpers
• dashboard widgets
• app bootstrap code

This forces better classification across feature, ui, data-access, util, and shell.

Ask for migration sequencing

For existing repos, request an ordered plan such as:

1. define apps and top-level libs
2. isolate utilities
3. move data-access modules
4. enforce tags and boundaries
5. update CI to affected commands
6. enable remote caching

This is more useful than a one-shot target diagram because it reduces migration risk.

Validate recommendations against your CI reality

Some nx-workspace-patterns guide suggestions only pay off if your CI environment supports them well. After the first output, ask:

• which targets should be cacheable first
• which jobs should switch to affected runs
• what assumptions depend on remote cache availability
• how to measure whether the new structure improved run time

Improve prompts after the first answer

A good second-round prompt is:

Revise the nx-workspace-patterns proposal for a team of 4 squads with separate ownership over web, admin, api, and shared platform code. Add project tags, import rules, and examples of bad boundaries to avoid.

This kind of iteration is better than asking for “more detail” because it sharpens decisions.

Watch for overengineering

Another common failure mode is adopting every library type too early. If your repo is still small, ask the skill to recommend the minimum viable Nx structure now and the trigger points for adding more layers later. That keeps the workspace usable instead of prematurely complex.

Pair this skill with official Nx docs

To get the best results from nx-workspace-patterns install and implementation, use the skill for architecture decisions and the official Nx docs for:

• exact commands
• plugin setup
• version-specific config changes
• executor and generator details

That combination gives better output than relying on either source alone.