@frontmcp/skills 0.0.1 → 1.0.0-beta.10

package/catalog/frontmcp-setup/references/frontmcp-skills-usage.md

@@ -0,0 +1,265 @@
+# FrontMCP Skills — Search, Install, and Usage
+
+FrontMCP ships with a catalog of development skills that teach AI agents (Claude Code, Codex) how to build FrontMCP servers. You can deliver these skills **statically** (copy to disk) or **dynamically** (search on demand via CLI).
+
+## When to Use This Skill
+
+### Must Use
+
+- Setting up a new FrontMCP project and need to discover which skills to install for your workflow
+- Configuring AI-assisted development (Claude Code or Codex) with FrontMCP skill files for the first time
+- Deciding between static skill installation and dynamic on-demand search for your team
+
+### Recommended
+
+- Exploring the FrontMCP skill catalog to find skills for a specific topic (auth, deployment, plugins, etc.)
+- Onboarding a new team member who needs to understand how FrontMCP skills are delivered and consumed
+- Optimizing token usage by switching from fully-static to a hybrid static/dynamic skill strategy
+
+### Skip When
+
+- You already know which specific skill you need and want to learn its content (use that skill directly, e.g., `frontmcp-development` or `frontmcp-config`)
+- You are scaffolding a brand-new FrontMCP project from scratch (use `frontmcp-setup` instead)
+- You need to create a custom skill for your own organization (use the `create-skill` reference in `frontmcp-development`)
+
+> **Decision:** Use this skill when you need to understand the skills system itself -- how to browse, install, manage, and deliver FrontMCP skills to AI agents.
+
+## Available Skills
+
+The catalog contains 6 router skills, each covering a domain:
+
+| Skill Name             | Category    | Description                                                                    |
+| ---------------------- | ----------- | ------------------------------------------------------------------------------ |
+| `frontmcp-setup`       | setup       | Project setup, scaffolding, Nx workspaces, storage backends                    |
+| `frontmcp-development` | development | Creating tools, resources, prompts, agents, providers, jobs, workflows, skills |
+| `frontmcp-deployment`  | deployment  | Build and deploy to Node, Vercel, Lambda, Cloudflare, CLI, browser, SDK        |
+| `frontmcp-testing`     | testing     | Testing with Jest and @frontmcp/testing                                        |
+| `frontmcp-config`      | config      | Transport, HTTP, throttle, elicitation, auth, sessions, storage                |
+| `frontmcp-guides`      | guides      | End-to-end examples and best practices                                         |
+
+Each router skill contains a SKILL.md with a routing table and a `references/` directory with detailed reference files.
+
+## Quick Start
+
+```bash
+# List all skills
+frontmcp skills list
+
+# List skills by category
+frontmcp skills list --category development
+
+# Show full skill content
+frontmcp skills show frontmcp-development
+
+# Install a skill for Claude Code
+frontmcp skills install frontmcp-development --provider claude
+
+# Install a skill for Codex
+frontmcp skills install frontmcp-setup --provider codex
+```
+
+## CLI Commands
+
+### `frontmcp skills search <query>`
+
+Semantic search through the catalog using weighted text matching (description 3x, tags 2x, name 1x):
+
+```bash
+frontmcp skills search "authentication oauth"
+frontmcp skills search "deploy vercel" --category deployment
+frontmcp skills search "plugin hooks" --tag middleware --limit 5
+```
+
+### `frontmcp skills list`
+
+List all skills, optionally filtered:
+
+```bash
+frontmcp skills list                          # All skills
+frontmcp skills list --category development   # Development skills only
+frontmcp skills list --tag redis              # Skills tagged with redis
+frontmcp skills list --bundle recommended     # Recommended bundle
+```
+
+### `frontmcp skills show <name>`
+
+Print the full SKILL.md content to stdout — useful for piping to AI context:
+
+```bash
+frontmcp skills show frontmcp-development    # Print development skill
+frontmcp skills show frontmcp-config         # Print config skill
+```
+
+### `frontmcp skills install <name>`
+
+Copy a skill to a provider-specific directory:
+
+```bash
+# Claude Code — installs to .claude/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-development --provider claude
+
+# Codex — installs to .codex/skills/<name>/SKILL.md
+frontmcp skills install frontmcp-setup --provider codex
+
+# Custom directory
+frontmcp skills install frontmcp-guides --dir ./my-skills
+```
+
+## Two Approaches: Static vs Dynamic
+
+### Static Installation (Copy to Disk)
+
+Install skills once — they live in your project and are always available:
+
+```bash
+# Install for Claude Code
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Install for Codex
+frontmcp skills install frontmcp-development --provider codex
+```
+
+**Directory structure after install:**
+
+```text
+my-project/
+├── .claude/
+│   └── skills/
+│       ├── frontmcp-setup/
+│       │   ├── SKILL.md
+│       │   └── references/
+│       ├── frontmcp-development/
+│       │   ├── SKILL.md
+│       │   └── references/
+│       └── frontmcp-config/
+│           ├── SKILL.md
+│           └── references/
+├── .codex/
+│   └── skills/
+│       └── frontmcp-development/
+│           ├── SKILL.md
+│           └── references/
+└── src/
+    └── ...
+```
+
+### Dynamic Search (On-Demand via CLI)
+
+Use the CLI to search and show skills on demand — no installation needed:
+
+```bash
+# Search for what you need
+frontmcp skills search "how to create a tool with zod"
+
+# Pipe skill content directly into context
+frontmcp skills show frontmcp-development
+```
+
+This works because `frontmcp skills show` outputs the full SKILL.md content to stdout.
+
+## Comparison: Static vs Dynamic
+
+| Aspect            | Static Install                        | Dynamic CLI Search                              |
+| ----------------- | ------------------------------------- | ----------------------------------------------- |
+| **Setup**         | `frontmcp skills install <name>` once | No setup — just use `frontmcp skills search`    |
+| **Availability**  | Always loaded by AI agent             | On-demand, requires CLI invocation              |
+| **Context usage** | Skills in system prompt (uses tokens) | Only loaded when searched (saves tokens)        |
+| **Updates**       | Re-install to update                  | Uses catalog bundled with the installed package |
+| **Offline**       | Works offline after install           | Needs catalog available                         |
+| **Best for**      | Core skills you use daily             | Occasional reference, exploration               |
+| **Token cost**    | Higher (all installed skills loaded)  | Lower (only searched skills loaded)             |
+
+### Recommended Approach
+
+**Install 2-4 core skills statically** for your most common workflows, and use dynamic search for everything else:
+
+```bash
+# Core skills — install statically
+frontmcp skills install frontmcp-setup --provider claude
+frontmcp skills install frontmcp-development --provider claude
+frontmcp skills install frontmcp-config --provider claude
+
+# Everything else — search on demand
+frontmcp skills search "deploy to vercel"
+frontmcp skills search "rate limiting"
+frontmcp skills show frontmcp-deployment
+```
+
+## Provider Directories
+
+| Provider    | Install directory                | Auto-loaded by            |
+| ----------- | -------------------------------- | ------------------------- |
+| Claude Code | `.claude/skills/<name>/SKILL.md` | Claude Code system prompt |
+| Codex       | `.codex/skills/<name>/SKILL.md`  | Codex agent context       |
+
+## Bundle Presets
+
+When scaffolding a project, use `--skills` to install a preset bundle:
+
+```bash
+# Recommended bundle (core skills for the deployment target)
+frontmcp create my-app --skills recommended
+
+# Minimal bundle (just project setup + create-tool)
+frontmcp create my-app --skills minimal
+
+# Full bundle (all skills)
+frontmcp create my-app --skills full
+
+# No skills
+frontmcp create my-app --skills none
+```
+
+## Available Categories
+
+```bash
+frontmcp skills list --category setup        # Project setup and scaffolding
+frontmcp skills list --category config       # Server configuration (transport, HTTP, throttle, auth)
+frontmcp skills list --category development  # Creating tools, resources, prompts, agents, skills
+frontmcp skills list --category deployment   # Build and deploy (node, vercel, lambda, cloudflare, cli, browser, sdk)
+frontmcp skills list --category testing      # Testing with Jest and @frontmcp/testing
+frontmcp skills list --category guides       # End-to-end examples and best practices
+```
+
+## Common Patterns
+
+| Pattern                     | Correct                                                                   | Incorrect                                       | Why                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| Installing a skill          | `frontmcp skills install frontmcp-development --provider claude`          | `cp node_modules/.../SKILL.md .claude/skills/`  | The CLI handles directory creation, naming, and reference files automatically                          |
+| Searching skills            | `frontmcp skills search "oauth authentication"`                           | `frontmcp skills list \| grep oauth`            | Search uses weighted text matching (description 3x, tags 2x) for better relevance                      |
+| Choosing delivery mode      | Install 2-4 core skills statically; search the rest on demand             | Install every skill statically into the project | Static skills consume tokens on every agent invocation; keep the set small                             |
+| Updating an installed skill | `frontmcp skills install frontmcp-development --provider claude` (re-run) | Manually editing the installed SKILL.md file    | Re-installing overwrites with the catalog bundled in the installed CLI version and preserves structure |
+| Filtering by category       | `frontmcp skills list --category deployment`                              | `frontmcp skills search "deployment"`           | `--category` uses the manifest taxonomy; search is for free-text queries                               |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] FrontMCP CLI is installed and available on PATH (`frontmcp --version`)
+- [ ] Target provider directory exists or will be created (`.claude/skills/` or `.codex/skills/`)
+- [ ] Desired skills are listed in `frontmcp skills list` output
+- [ ] Bundle preset matches project needs (`minimal`, `recommended`, or `full`)
+
+### Runtime
+
+- [ ] Installed skills appear in the correct provider directory after `frontmcp skills install`
+- [ ] `frontmcp skills show <name>` outputs the full SKILL.md content to stdout
+- [ ] `frontmcp skills search <query>` returns relevant results ranked by relevance
+- [ ] AI agent (Claude Code or Codex) loads installed skills in its system prompt context
+
+## Troubleshooting
+
+| Problem                                               | Cause                                                               | Solution                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `frontmcp skills search` returns no results           | Query terms do not match any skill name, description, or tags       | Broaden the query, try synonyms, or use `frontmcp skills list` to browse all available skills             |
+| Installed skill not picked up by Claude Code          | Skill was installed to wrong directory or provider flag was omitted | Re-install with `--provider claude` and verify the file exists at `.claude/skills/<name>/SKILL.md`        |
+| `frontmcp skills install` fails with permission error | Target directory is read-only or owned by a different user          | Check directory permissions; use `--dir` flag to specify an alternative writable path                     |
+| Skill content is outdated after a CLI upgrade         | Static installs are point-in-time snapshots of the catalog          | Re-run `frontmcp skills install <name> --provider claude` to fetch the latest version                     |
+| Too many tokens consumed by agent context             | All skills installed statically, inflating the system prompt        | Uninstall rarely-used skills and switch to dynamic search (`frontmcp skills search`) for occasional needs |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>
+- **Related skills:** `frontmcp-setup`, `frontmcp-development`, `frontmcp-config`, `frontmcp-deployment`

package/catalog/{setup/multi-app-composition/SKILL.md → frontmcp-setup/references/multi-app-composition.md}

@@ -1,34 +1,28 @@
----
-name: multi-app-composition
-description: Compose multiple apps in a single server with shared tools, scoped auth, and external app loading. Use when building multi-app servers, sharing tools between apps, loading ESM or remote apps, or configuring per-app auth.
-tags: [multi-app, composition, architecture, scope, shared-tools]
-priority: 9
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/features/multi-app-composition
----
-
 # Multi-App Composition
 
 Compose multiple `@App` classes into a single `@FrontMcp` server. Each app contributes its own tools, resources, prompts, skills, and plugins. Apps can be local classes, npm packages loaded at runtime, or remote MCP servers proxied through your gateway.
 
-## When to Use Multi-App
+## When to Use This Skill
 
-**Single app** is sufficient when your server has one logical domain (e.g., a calculator, a file manager). Define one `@App` class with all tools and resources:
+### Must Use
 
-```typescript
-@App({ name: 'Calculator', tools: [AddTool, SubtractTool] })
-class CalcApp {}
+- Composing multiple `@App` classes with separate domains into a single `@FrontMcp` server
+- Aggregating external MCP servers via `app.remote()` or npm packages via `app.esm()` into a unified gateway
+- Configuring per-app authentication modes (e.g., one app public, another requiring OAuth)
 
-@FrontMcp({
-  info: { name: 'my-server', version: '1.0.0' },
-  apps: [CalcApp],
-})
-export default class Server {}
-```
+### Recommended
 
-**Multi-app** is needed when you have multiple domains, separate auth requirements, external MCP servers to aggregate, or npm packages to compose at runtime. The `apps` array in `@FrontMcp` accepts any combination of local classes, ESM packages, and remote servers.
+- Setting up shared tools, resources, or plugins that span all apps in the server
+- Isolating apps with `standalone: true` or `standalone: 'includeInParent'` for scoped auth or session separation
+- Namespacing tools from multiple apps or remote servers to prevent naming collisions
+
+### Skip When
+
+- Your server has a single logical domain with one `@App` class (see `project-structure-standalone`)
+- You are scaffolding an Nx monorepo workspace and need generator commands (see `project-structure-nx`)
+- You need to create individual tools, resources, or prompts rather than compose apps (see `create-tool`)
+
+> **Decision:** Use this skill when you need to compose two or more apps -- local, ESM, or remote -- into a single FrontMCP server with shared or scoped capabilities.
 
 ## Local Apps
 
@@ -356,3 +350,51 @@ class AdminApp {}
 })
 export default class Server {}
 ```
+
+## Common Patterns
+
+| Pattern              | Correct                                                                         | Incorrect                                                                     | Why                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Shared tools         | `@FrontMcp({ tools: [HealthCheckTool] })` (server-level)                        | Duplicating the tool class in every `@App` `tools` array                      | Server-level tools are automatically shared across all apps without duplication                   |
+| App namespacing      | `@App({ id: 'billing', name: 'Billing', tools: [ChargeTool] })`                 | Omitting `id` when multiple apps have tools with the same name                | The `id` field controls the namespace prefix (`billing:charge_card`); without it collisions occur |
+| Remote auth          | `remoteAuth: { mode: 'static', credentials: { type: 'bearer', value: token } }` | Passing the token directly as a string to `remoteAuth`                        | `remoteAuth` expects a structured object with `mode` and `credentials` fields                     |
+| Standalone isolation | `standalone: true` for fully isolated apps                                      | `standalone: true` when you still want tools visible in the parent server     | Use `standalone: 'includeInParent'` to get scope isolation with parent visibility                 |
+| Per-app auth         | `auth: { mode: 'remote', idpProviderUrl: '...' }` on `@App`                     | Configuring auth only at the `@FrontMcp` level when apps need different modes | Apps without their own `auth` inherit server-level config; set per-app `auth` for mixed modes     |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@FrontMcp` `apps` array includes all local, ESM, and remote apps
+- [ ] Each `@App` has a unique `id` (or unique `name` if `id` is omitted)
+- [ ] `namespace` is set on ESM and remote apps to prevent tool name collisions
+- [ ] Server-level `tools`, `plugins`, and `providers` are declared for shared capabilities
+
+### Runtime
+
+- [ ] All app tools appear in `tools/list` with correct namespace prefixes
+- [ ] Shared tools appear without a namespace prefix
+- [ ] `standalone: true` apps are isolated and do not appear in parent tool listing
+- [ ] `standalone: 'includeInParent'` apps have isolated scope but visible tools
+- [ ] Per-app auth modes are enforced independently per app
+
+### Remote Apps
+
+- [ ] `app.remote()` URL is reachable and returns valid MCP capabilities
+- [ ] `remoteAuth` credentials are correct and not expired
+- [ ] `fallbackToSSE` is enabled if the remote server does not support Streamable HTTP
+
+## Troubleshooting
+
+| Problem                                  | Cause                                                       | Solution                                                                                                 |
+| ---------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Tool name collision between apps         | Multiple apps register tools with the same name and no `id` | Set unique `id` on each `@App` or use `namespace` on ESM/remote apps                                     |
+| Remote app tools not appearing           | Remote server is unreachable or returns empty capabilities  | Verify the URL, check `transportOptions.timeout`, and ensure `remoteAuth` is correct                     |
+| Shared plugin not applied to an app      | Plugin declared on `@App` instead of `@FrontMcp`            | Move the plugin to the `@FrontMcp` `plugins` array for server-wide application                           |
+| `standalone: true` app tools not visible | Standalone apps are fully isolated by design                | Use `standalone: 'includeInParent'` to expose tools in the parent server while keeping scope isolation   |
+| Per-app auth not working                 | App does not declare its own `auth` field                   | Add `auth` configuration directly on the `@App` decorator; omitted `auth` inherits server-level defaults |
+
+## Reference
+
+- [Multi-App Composition Documentation](https://docs.agentfront.dev/frontmcp/features/multi-app-composition)
+- Related skills: `project-structure-standalone`, `project-structure-nx`, `configure-auth`, `create-tool`

package/catalog/{setup/nx-workflow/SKILL.md → frontmcp-setup/references/nx-workflow.md}

@@ -1,21 +1,28 @@
----
-name: nx-workflow
-description: Complete Nx monorepo workflow for FrontMCP with all generators, build, test, and deployment commands. Use when working in an Nx workspace, running generators, or managing monorepo builds.
-tags: [nx, monorepo, generators, workflow, scaffold]
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/nx-plugin/overview
----
-
 # Nx Monorepo Workflow for FrontMCP
 
 Use the `@frontmcp/nx` plugin to scaffold, build, test, and deploy FrontMCP projects in an Nx monorepo. The plugin provides generators for every FrontMCP primitive (tools, resources, prompts, skills, agents, plugins, adapters, providers, flows, jobs, workflows) and deployment shells for multiple targets.
 
-## When to Use Nx
+## When to Use This Skill
+
+### Must Use
+
+- Your project contains multiple apps or shared libraries in a monorepo structure
+- You need fine-grained build caching and affected-only testing in CI
+- You are scaffolding a new FrontMCP workspace with multiple deployment targets
+
+### Recommended
+
+- You want generator-based scaffolding for every FrontMCP primitive (tools, resources, prompts, skills, etc.)
+- You need to visualize and manage complex dependency graphs across projects
+- Your team benefits from parallelized builds and consistent project structure
+
+### Skip When
 
-Use the Nx workflow when your project has multiple apps, shared libraries, or needs fine-grained build caching and affected-only testing. For simple single-server projects, the standalone `frontmcp create` approach is sufficient.
+- Your project is a single standalone MCP server with no shared libraries -- use `frontmcp create` instead
+- You are adding FrontMCP to an existing non-Nx build system (Turborepo, Lerna) -- use `setup-project` instead
+- You only need to configure storage or auth without workspace scaffolding -- use `setup-sqlite` or `setup-redis` instead
+
+> **Decision:** Use this skill when managing a multi-project FrontMCP monorepo; skip it for single-server projects.
 
 ## Step 1 -- Initialize the Workspace
 
@@ -43,13 +50,13 @@ nx g @frontmcp/nx:workspace my-workspace
 
 The workspace generator creates the directory structure (`apps/`, `libs/`, `servers/`) and base configuration. It accepts these options:
 
-| Option            | Type                                 | Default    | Description                      |
-| ----------------- | ------------------------------------ | ---------- | -------------------------------- |
-| `name`            | `string`                             | (required) | Workspace name                   |
-| `packageManager`  | `'npm' \| 'yarn' \| 'pnpm' \| 'bun'` | `'npm'`    | Package manager to use           |
-| `skipInstall`     | `boolean`                            | `false`    | Skip package installation        |
-| `skipGit`         | `boolean`                            | `false`    | Skip git initialization          |
-| `createSampleApp` | `boolean`                            | `true`     | Create a sample demo application |
+| Option            | Type                        | Default    | Description                      |
+| ----------------- | --------------------------- | ---------- | -------------------------------- |
+| `name`            | `string`                    | (required) | Workspace name                   |
+| `packageManager`  | `'npm' \| 'yarn' \| 'pnpm'` | `'npm'`    | Package manager to use           |
+| `skipInstall`     | `boolean`                   | `false`    | Skip package installation        |
+| `skipGit`         | `boolean`                   | `false`    | Skip git initialization          |
+| `createSampleApp` | `boolean`                   | `true`     | Create a sample demo application |
 
 ## Step 2 -- Generate Apps and Libraries
 
@@ -252,7 +259,7 @@ nx run-many -t build,test,lint
 
 After scaffolding, the workspace follows this directory layout:
 
-```
+```text
 my-project/
   apps/
     my-app/
@@ -355,3 +362,53 @@ Complete list of all `@frontmcp/nx` generators from `generators.json`:
 | `job`           | `nx g @frontmcp/nx:job <name> --project=<app>`           | Generate a @Job class                                                |
 | `workflow`      | `nx g @frontmcp/nx:workflow <name> --project=<app>`      | Generate a @Workflow class                                           |
 | `auth-provider` | `nx g @frontmcp/nx:auth-provider <name> --project=<app>` | Generate an @AuthProvider class                                      |
+
+## Common Patterns
+
+| Pattern                    | Correct                                                 | Incorrect                              | Why                                                                                       |
+| -------------------------- | ------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Primitive generator target | `nx g @frontmcp/nx:tool my-tool --project=my-app`       | `nx g @frontmcp/nx:tool my-tool`       | All primitive generators require `--project` to specify which app receives the file       |
+| Test file naming           | `my-tool.tool.spec.ts`                                  | `my-tool.tool.test.ts`                 | FrontMCP enforces `.spec.ts` extension; `.test.ts` files are not picked up by Jest config |
+| Affected-only CI testing   | `nx affected -t test`                                   | `nx run-many -t test`                  | `affected` only runs tests for changed projects, saving CI time and compute               |
+| Server composition         | `nx g @frontmcp/nx:server my-server --apps=app-a,app-b` | Manually importing apps in `main.ts`   | The server generator wires app composition and deployment config automatically            |
+| Build before deploy        | `nx build my-server` (builds server + all deps)         | Building each lib and app individually | Nx resolves the dependency graph and builds in the correct order with caching             |
+
+## Verification Checklist
+
+### Workspace Setup
+
+- [ ] `@frontmcp/nx` is listed in `devDependencies`
+- [ ] `nx.json` exists at workspace root with valid configuration
+- [ ] `apps/`, `libs/`, and `servers/` directories exist
+
+### Generation
+
+- [ ] Generated files are placed in the correct directory (`apps/<app>/src/<type>/`)
+- [ ] Barrel exports (`index.ts`) are updated after each generator run
+- [ ] `.spec.ts` test file is created alongside each generated class
+
+### Build and Test
+
+- [ ] `nx build <server>` completes without TypeScript errors or warnings
+- [ ] `nx test <app>` passes with 95%+ coverage
+- [ ] `nx affected -t test` correctly identifies changed projects
+
+### Development Workflow
+
+- [ ] `nx serve <server>` or `nx dev <server>` starts the server successfully
+- [ ] `nx graph` renders the project dependency graph in the browser
+
+## Troubleshooting
+
+| Problem                                        | Cause                                                       | Solution                                                                                             |
+| ---------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `Cannot find module '@frontmcp/nx'`            | Plugin not installed                                        | Run `yarn add -D @frontmcp/nx` and ensure it appears in `devDependencies`                            |
+| Generator creates files in the wrong directory | Missing or incorrect `--project` flag                       | Always pass `--project=<app-name>` for primitive generators; verify the app exists in `apps/`        |
+| `nx affected` runs nothing despite changes     | Base branch not configured or no dependency link            | Check `nx.json` for `defaultBase` setting; verify the changed file belongs to a project in the graph |
+| Build fails with circular dependency error     | Library A imports from Library B and vice versa             | Use `nx graph` to visualize the cycle; extract shared code into a new library                        |
+| Cache not working (full rebuild every time)    | Missing or misconfigured `cacheableOperations` in `nx.json` | Ensure `build`, `test`, and `lint` are listed in `targetDefaults` with `cache: true`                 |
+
+## Reference
+
+- **Docs:** [Nx Plugin Overview](https://docs.agentfront.dev/frontmcp/nx-plugin/overview)
+- **Related skills:** `setup-project`, `setup-sqlite`, `setup-redis`