@frontmcp/skills 0.0.1

package/catalog/setup/nx-workflow/SKILL.md

@@ -0,0 +1,357 @@
+---
+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
+
+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.
+
+## Step 1 -- Initialize the Workspace
+
+### Option A: Scaffold a new Nx workspace with the FrontMCP CLI
+
+```bash
+npx frontmcp create my-project --nx
+```
+
+This creates a full Nx workspace with `@frontmcp/nx` pre-installed, sample app, and workspace configuration.
+
+### Option B: Add FrontMCP to an existing Nx workspace
+
+Install the plugin:
+
+```bash
+yarn add -D @frontmcp/nx
+```
+
+Then initialize the workspace structure:
+
+```bash
+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 |
+
+## Step 2 -- Generate Apps and Libraries
+
+### Generate an App
+
+```bash
+nx g @frontmcp/nx:app my-app
+```
+
+Creates an `@App`-decorated class in `apps/my-app/` with a tools directory, barrel exports, and project configuration. The `--project` flag is not needed for app generation since the app is the project.
+
+### Generate a Shared Library
+
+```bash
+nx g @frontmcp/nx:lib my-lib
+```
+
+Creates a shared library in `libs/my-lib/` with TypeScript configuration, Jest setup, and barrel exports. Use libraries for shared providers, utilities, and types that multiple apps consume.
+
+### Generate a Server (Deployment Shell)
+
+```bash
+nx g @frontmcp/nx:server my-server --deploymentTarget=node --apps=my-app
+```
+
+Creates a `@FrontMcp`-decorated server class in `servers/my-server/` that composes one or more apps. The server is the deployment unit.
+
+| Option             | Type                                             | Default          | Description                           |
+| ------------------ | ------------------------------------------------ | ---------------- | ------------------------------------- |
+| `name`             | `string`                                         | (required)       | Server name                           |
+| `apps`             | `string`                                         | (required)       | Comma-separated app names to compose  |
+| `deploymentTarget` | `'node' \| 'vercel' \| 'lambda' \| 'cloudflare'` | `'node'`         | Deployment target platform            |
+| `directory`        | `string`                                         | `servers/<name>` | Override the default directory        |
+| `redis`            | `'docker' \| 'existing' \| 'none'`               | `'none'`         | Redis setup option (node target only) |
+| `skills`           | `'recommended' \| 'minimal' \| 'full' \| 'none'` | `'recommended'`  | Skills bundle to include              |
+
+## Step 3 -- Generate MCP Primitives
+
+All primitive generators require `--project` to specify which app receives the generated file. Each generator creates the implementation file, a `.spec.ts` test file, and updates barrel exports.
+
+### Tool
+
+```bash
+nx g @frontmcp/nx:tool my-tool --project=my-app
+```
+
+Creates a `@Tool`-decorated class extending `ToolContext` in `apps/my-app/src/tools/`. Use the `--directory` option to place it in a subdirectory within `src/tools/`.
+
+### Resource
+
+```bash
+nx g @frontmcp/nx:resource my-resource --project=my-app
+```
+
+Creates a `@Resource`-decorated class extending `ResourceContext` in `apps/my-app/src/resources/`.
+
+### Prompt
+
+```bash
+nx g @frontmcp/nx:prompt my-prompt --project=my-app
+```
+
+Creates a `@Prompt`-decorated class extending `PromptContext` in `apps/my-app/src/prompts/`.
+
+### Skill (Class-Based)
+
+```bash
+nx g @frontmcp/nx:skill my-skill --project=my-app
+```
+
+Creates a `@Skill`-decorated class extending `SkillContext` in `apps/my-app/src/skills/`.
+
+### Skill (SKILL.md Directory)
+
+```bash
+nx g @frontmcp/nx:skill-dir my-skill --project=my-app
+```
+
+Creates a `SKILL.md`-based skill directory in `apps/my-app/src/skills/my-skill/` with a template SKILL.md file. Use this for declarative skills that are defined by markdown instructions rather than code.
+
+### Agent
+
+```bash
+nx g @frontmcp/nx:agent my-agent --project=my-app
+```
+
+Creates an `@Agent`-decorated class in `apps/my-app/src/agents/`. Agents are autonomous AI components with their own LLM providers and isolated scopes, automatically exposed as `use-agent:<agent_id>` tools.
+
+### Plugin
+
+```bash
+nx g @frontmcp/nx:plugin my-plugin --project=my-app
+```
+
+Creates a `@Plugin` class extending `DynamicPlugin` in `apps/my-app/src/plugins/`. Plugins participate in lifecycle events and can contribute additional capabilities.
+
+### Adapter
+
+```bash
+nx g @frontmcp/nx:adapter my-adapter --project=my-app
+```
+
+Creates an `@Adapter` class extending `DynamicAdapter` in `apps/my-app/src/adapters/`. Adapters convert external definitions (OpenAPI, Lambda, etc.) into generated tools, resources, and prompts.
+
+### Provider
+
+```bash
+nx g @frontmcp/nx:provider my-provider --project=my-app
+```
+
+Creates a `@Provider` class in `apps/my-app/src/providers/`. Providers are named singletons resolved via DI (e.g., database pools, API clients, config).
+
+### Flow
+
+```bash
+nx g @frontmcp/nx:flow my-flow --project=my-app
+```
+
+Creates a `@Flow` class extending `FlowBase` in `apps/my-app/src/flows/`. Flows define execution pipelines with hooks and stages.
+
+### Job
+
+```bash
+nx g @frontmcp/nx:job my-job --project=my-app
+```
+
+Creates a `@Job` class in `apps/my-app/src/jobs/`. Jobs are pure executable units with strict input/output schemas.
+
+### Workflow
+
+```bash
+nx g @frontmcp/nx:workflow my-workflow --project=my-app
+```
+
+Creates a `@Workflow` class in `apps/my-app/src/workflows/`. Workflows connect jobs into managed steps with triggers.
+
+### Auth Provider
+
+```bash
+nx g @frontmcp/nx:auth-provider my-auth --project=my-app
+```
+
+Creates an `@AuthProvider` class in `apps/my-app/src/auth-providers/`. Auth providers handle session-based authentication (e.g., GitHub OAuth, Google OAuth).
+
+## Step 4 -- Build and Test
+
+### Build a Single Project
+
+```bash
+nx build my-server
+```
+
+Builds the server and all its dependencies in the correct order. Nx caches build outputs so subsequent builds of unchanged projects are instant.
+
+### Test a Single Project
+
+```bash
+nx test my-app
+```
+
+Runs Jest tests for the specified project. Test files must use `.spec.ts` extension (not `.test.ts`).
+
+### Build All Projects
+
+```bash
+nx run-many -t build
+```
+
+Builds every project in the workspace. Nx parallelizes independent builds automatically.
+
+### Test All Projects
+
+```bash
+nx run-many -t test
+```
+
+Runs tests for every project in the workspace.
+
+### Test Only Affected Projects
+
+```bash
+nx affected -t test
+```
+
+Runs tests only for projects affected by changes since the last commit (or since the base branch). This is the fastest way to validate changes in CI.
+
+### Build Only Affected Projects
+
+```bash
+nx affected -t build
+```
+
+### Run Multiple Targets
+
+```bash
+nx run-many -t build,test,lint
+```
+
+## Step 5 -- Workspace Structure
+
+After scaffolding, the workspace follows this directory layout:
+
+```
+my-project/
+  apps/
+    my-app/
+      src/
+        tools/         # @Tool classes
+        resources/     # @Resource classes
+        prompts/       # @Prompt classes
+        skills/        # @Skill classes and SKILL.md dirs
+        agents/        # @Agent classes
+        plugins/       # @Plugin classes
+        adapters/      # @Adapter classes
+        providers/     # @Provider classes
+        flows/         # @Flow classes
+        jobs/          # @Job classes
+        workflows/     # @Workflow classes
+        auth-providers/ # @AuthProvider classes
+        my-app.app.ts  # @App class
+        index.ts       # barrel exports
+      project.json
+      tsconfig.json
+      jest.config.ts
+  libs/
+    my-lib/
+      src/
+        index.ts
+      project.json
+  servers/
+    my-server/
+      src/
+        main.ts        # @FrontMcp server (default export)
+      project.json
+      Dockerfile       # (node target)
+  nx.json
+  tsconfig.base.json
+  package.json
+```
+
+## Step 6 -- Development Workflow
+
+### Serve in Development
+
+```bash
+nx serve my-server
+```
+
+Or use the FrontMCP dev command:
+
+```bash
+nx dev my-server
+```
+
+### Generate, Build, and Test a New Feature
+
+A typical workflow for adding a new tool:
+
+```bash
+# 1. Generate the tool scaffold
+nx g @frontmcp/nx:tool calculate-tax --project=billing-app
+
+# 2. Implement the tool logic in apps/billing-app/src/tools/calculate-tax.tool.ts
+
+# 3. Run tests for the affected app
+nx test billing-app
+
+# 4. Build the server that includes this app
+nx build billing-server
+
+# 5. Or test everything affected by your changes
+nx affected -t test
+```
+
+### Visualize the Project Graph
+
+```bash
+nx graph
+```
+
+Opens an interactive visualization of project dependencies in your browser. Useful for understanding how apps, libs, and servers relate to each other.
+
+## Generator Reference
+
+Complete list of all `@frontmcp/nx` generators from `generators.json`:
+
+| Generator       | Command                                                  | Description                                                          |
+| --------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
+| `workspace`     | `nx g @frontmcp/nx:workspace <name>`                     | Scaffold a full FrontMCP Nx monorepo with apps/, libs/, and servers/ |
+| `app`           | `nx g @frontmcp/nx:app <name>`                           | Generate a FrontMCP application in apps/                             |
+| `lib`           | `nx g @frontmcp/nx:lib <name>`                           | Generate a shared library in libs/                                   |
+| `server`        | `nx g @frontmcp/nx:server <name> --apps=<apps>`          | Generate a deployment shell in servers/                              |
+| `tool`          | `nx g @frontmcp/nx:tool <name> --project=<app>`          | Generate a @Tool class                                               |
+| `resource`      | `nx g @frontmcp/nx:resource <name> --project=<app>`      | Generate a @Resource or @ResourceTemplate class                      |
+| `prompt`        | `nx g @frontmcp/nx:prompt <name> --project=<app>`        | Generate a @Prompt class                                             |
+| `skill`         | `nx g @frontmcp/nx:skill <name> --project=<app>`         | Generate a @Skill class                                              |
+| `skill-dir`     | `nx g @frontmcp/nx:skill-dir <name> --project=<app>`     | Generate a SKILL.md-based skill directory                            |
+| `agent`         | `nx g @frontmcp/nx:agent <name> --project=<app>`         | Generate an @Agent class                                             |
+| `plugin`        | `nx g @frontmcp/nx:plugin <name> --project=<app>`        | Generate a @Plugin class extending DynamicPlugin                     |
+| `adapter`       | `nx g @frontmcp/nx:adapter <name> --project=<app>`       | Generate an @Adapter class extending DynamicAdapter                  |
+| `provider`      | `nx g @frontmcp/nx:provider <name> --project=<app>`      | Generate a @Provider class for dependency injection                  |
+| `flow`          | `nx g @frontmcp/nx:flow <name> --project=<app>`          | Generate a @Flow class extending FlowBase                            |
+| `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                                      |

package/catalog/setup/project-structure-nx/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: project-structure-nx
+description: Best practices for organizing a FrontMCP Nx monorepo -- apps, libs, servers, generators, and multi-app composition. Use when working with frontmcp create --nx or an Nx workspace.
+tags: [project, structure, nx, monorepo, organization, best-practices]
+priority: 8
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/nx-plugin/overview
+---
+
+# Nx Monorepo Project Structure
+
+When you scaffold with `frontmcp create --nx` or add FrontMCP to an existing Nx workspace, the recommended layout separates apps, shared libraries, and server entry points:
+
+```
+my-workspace/
+├── apps/                     # @App classes (one app per directory)
+│   ├── billing/
+│   │   ├── src/
+│   │   │   ├── billing.app.ts
+│   │   │   ├── tools/
+│   │   │   ├── resources/
+│   │   │   └── providers/
+│   │   ├── project.json
+│   │   └── tsconfig.json
+│   └── crm/
+│       ├── src/
+│       │   ├── crm.app.ts
+│       │   ├── tools/
+│       │   └── resources/
+│       ├── project.json
+│       └── tsconfig.json
+├── libs/                     # Shared libraries
+│   └── shared-utils/
+│       ├── src/
+│       │   └── index.ts
+│       ├── project.json
+│       └── tsconfig.json
+├── servers/                  # @FrontMcp servers composing apps
+│   └── gateway/
+│       ├── src/
+│       │   └── main.ts       # @FrontMcp default export
+│       ├── project.json
+│       └── tsconfig.json
+├── nx.json
+├── tsconfig.base.json
+├── CLAUDE.md                 # AI config (auto-generated)
+├── AGENTS.md
+├── .mcp.json
+└── .cursorrules
+```
+
+## Directory Roles
+
+### apps/ -- Application Modules
+
+Each directory under `apps/` contains a single `@App` class with its tools, resources, prompts, providers, and plugins:
+
+```typescript
+// apps/billing/src/billing.app.ts
+import { App } from '@frontmcp/sdk';
+import { CreateInvoiceTool } from './tools/create-invoice.tool';
+import { InvoiceResource } from './resources/invoice.resource';
+import { StripeProvider } from './providers/stripe.provider';
+
+@App({
+  name: 'billing',
+  tools: [CreateInvoiceTool],
+  resources: [InvoiceResource],
+  providers: [StripeProvider],
+})
+export class BillingApp {}
+```
+
+Apps are self-contained and independently testable. They do not import from other apps -- shared code goes in `libs/`.
+
+### libs/ -- Shared Libraries
+
+Shared providers, utilities, types, and common logic live under `libs/`:
+
+```typescript
+// libs/shared-utils/src/index.ts
+export { formatCurrency } from './format-currency';
+export { DatabaseProvider } from './database.provider';
+export type { AppConfig } from './app-config.interface';
+```
+
+Apps and servers import from libs using Nx path aliases configured in `tsconfig.base.json`:
+
+```typescript
+import { DatabaseProvider } from '@my-workspace/shared-utils';
+```
+
+### servers/ -- FrontMcp Entry Points
+
+A server composes multiple apps into a single `@FrontMcp` entry point:
+
+```typescript
+// servers/gateway/src/main.ts
+import { FrontMcp } from '@frontmcp/sdk';
+import { BillingApp } from '@my-workspace/billing';
+import { CrmApp } from '@my-workspace/crm';
+
+@FrontMcp({
+  info: { name: 'gateway', version: '1.0.0' },
+  apps: [BillingApp, CrmApp],
+})
+class GatewayServer {}
+
+export default GatewayServer;
+```
+
+You can have multiple servers composing different combinations of apps (e.g., a public-facing server and an internal admin server).
+
+## Nx Generators
+
+The `@frontmcp/nx-plugin` package provides generators for all entity types:
+
+```bash
+# Generate a new app
+nx g @frontmcp/nx-plugin:app crm
+
+# Generate entities within an app
+nx g @frontmcp/nx-plugin:tool lookup-user --project=crm
+nx g @frontmcp/nx-plugin:resource user-profile --project=crm
+nx g @frontmcp/nx-plugin:prompt summarize --project=crm
+nx g @frontmcp/nx-plugin:provider database --project=crm
+nx g @frontmcp/nx-plugin:plugin logging --project=crm
+nx g @frontmcp/nx-plugin:agent research --project=crm
+nx g @frontmcp/nx-plugin:job cleanup --project=crm
+
+# Generate a new server
+nx g @frontmcp/nx-plugin:server gateway
+
+# Generate a shared library
+nx g @frontmcp/nx-plugin:lib shared-utils
+```
+
+## Build and Test Commands
+
+```bash
+# Build a specific server
+nx build gateway
+
+# Test a specific app
+nx test billing
+
+# Run all tests
+nx run-many -t test
+
+# Build all projects
+nx run-many -t build
+
+# Lint everything
+nx run-many -t lint
+```
+
+Nx caches build and test results. Subsequent runs for unchanged projects are instant.
+
+## AI Configuration Files
+
+FrontMCP auto-generates AI configuration files at the workspace root:
+
+| File           | Purpose                                  |
+| -------------- | ---------------------------------------- |
+| `CLAUDE.md`    | Instructions for Claude Code / Claude AI |
+| `AGENTS.md`    | Instructions for agent-based AI tools    |
+| `.mcp.json`    | MCP server configuration for AI IDEs     |
+| `.cursorrules` | Rules for Cursor AI editor               |
+
+These files are regenerated when you run generators or modify your workspace structure. They help AI tools understand your project layout and coding conventions.
+
+## Dependency Graph
+
+Nx enforces a clear dependency hierarchy:
+
+```
+servers/ --> apps/ --> libs/
+```
+
+- **servers** can import from **apps** and **libs**
+- **apps** can import from **libs** only (never from other apps or servers)
+- **libs** can import from other **libs** only
+
+Use `nx graph` to visualize the dependency graph and ensure no circular imports exist.

package/catalog/setup/project-structure-standalone/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: project-structure-standalone
+description: Best practices for organizing a standalone FrontMCP project -- file layout, naming conventions, and folder hierarchy. Use when scaffolding with frontmcp create or organizing an existing standalone project.
+tags: [project, structure, standalone, organization, best-practices]
+priority: 8
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/getting-started/quickstart
+---
+
+# Standalone Project Structure
+
+When you run `frontmcp create`, the CLI scaffolds a standalone project with the following layout:
+
+```
+my-project/
+├── src/
+│   ├── main.ts              # @FrontMcp server entry (default export)
+│   ├── my-app.app.ts        # @App class
+│   ├── tools/               # @Tool classes (*.tool.ts)
+│   ├── resources/            # @Resource classes (*.resource.ts)
+│   ├── prompts/              # @Prompt classes (*.prompt.ts)
+│   ├── agents/               # @Agent classes (*.agent.ts)
+│   ├── skills/               # @Skill classes or SKILL.md dirs
+│   ├── providers/            # @Provider classes (*.provider.ts)
+│   ├── plugins/              # @Plugin classes (*.plugin.ts)
+│   └── jobs/                 # @Job classes (*.job.ts)
+├── e2e/                      # E2E tests (*.e2e.spec.ts)
+├── skills/                   # Catalog skills (from --skills flag)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
+
+## File Naming Conventions
+
+Every entity type uses a consistent `<name>.<type>.ts` pattern:
+
+| Entity   | File Pattern    | Example                      |
+| -------- | --------------- | ---------------------------- |
+| Tool     | `*.tool.ts`     | `fetch-weather.tool.ts`      |
+| Resource | `*.resource.ts` | `user-profile.resource.ts`   |
+| Prompt   | `*.prompt.ts`   | `summarize.prompt.ts`        |
+| Agent    | `*.agent.ts`    | `research.agent.ts`          |
+| Skill    | `*.skill.ts`    | `calendar.skill.ts`          |
+| Provider | `*.provider.ts` | `database.provider.ts`       |
+| Plugin   | `*.plugin.ts`   | `logging.plugin.ts`          |
+| Job      | `*.job.ts`      | `cleanup.job.ts`             |
+| Test     | `*.spec.ts`     | `fetch-weather.tool.spec.ts` |
+| E2E Test | `*.e2e.spec.ts` | `api.e2e.spec.ts`            |
+
+**One class per file.** Keep each tool, resource, prompt, etc. in its own file.
+
+## Entry Point: main.ts
+
+`main.ts` default-exports the `@FrontMcp` server class. This is the file FrontMCP loads at startup:
+
+```typescript
+import { FrontMcp } from '@frontmcp/sdk';
+import { MyApp } from './my-app.app';
+
+@FrontMcp({
+  info: { name: 'my-project', version: '1.0.0' },
+  apps: [MyApp],
+})
+class MyServer {}
+
+export default MyServer;
+```
+
+## App Class
+
+The `@App` class groups tools, resources, prompts, plugins, and providers together:
+
+```typescript
+import { App } from '@frontmcp/sdk';
+import { FetchWeatherTool } from './tools/fetch-weather.tool';
+import { DatabaseProvider } from './providers/database.provider';
+
+@App({
+  name: 'my-app',
+  tools: [FetchWeatherTool],
+  providers: [DatabaseProvider],
+})
+export class MyApp {}
+```
+
+## Development Workflow
+
+### Start development server
+
+```bash
+frontmcp dev
+```
+
+Watches for file changes and restarts automatically.
+
+### Build for production
+
+```bash
+frontmcp build --target node
+frontmcp build --target bun
+frontmcp build --target cloudflare-workers
+```
+
+The `--target` flag determines the output format and runtime optimizations.
+
+### Run tests
+
+```bash
+# Unit tests
+jest
+
+# E2E tests
+jest --config e2e/jest.config.ts
+```
+
+## Organizing by Feature
+
+For larger standalone projects, group related entities into feature folders:
+
+```
+src/
+├── main.ts
+├── my-app.app.ts
+├── billing/
+│   ├── create-invoice.tool.ts
+│   ├── invoice.resource.ts
+│   └── billing.provider.ts
+├── users/
+│   ├── lookup-user.tool.ts
+│   ├── user-profile.resource.ts
+│   └── users.provider.ts
+└── plugins/
+    └── logging.plugin.ts
+```
+
+Feature folders work well when your project has multiple related tools and resources that share a domain.
+
+## Skills Directory
+
+The top-level `skills/` directory (outside `src/`) holds catalog skills added via the `--skills` flag during `frontmcp create`. Each skill is a folder containing a `SKILL.md` file:
+
+```
+skills/
+├── create-tool/
+│   └── SKILL.md
+└── setup-project/
+    └── SKILL.md
+```
+
+Skills inside `src/skills/` are `@Skill` classes that are part of your application code.