@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/frontmcp-development/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: frontmcp-development
-description: 'Use when you want to create a tool, add a resource, build a prompt, write a provider, implement an adapter, add OpenAPI integration, create a plugin, agent, job, or workflow. The skill for BUILDING any FrontMCP component.'
+description: 'Use when building any FrontMCP server component other than a tool (for tools, use create-tool). Covers @Resource static resources and parameterized URI templates; @Prompt reusable prompts (RAG, multi-turn); @Provider singleton dependency-injection providers (database pools, API clients); @Agent autonomous LLM agents (Anthropic, OpenAI) and swarms; @Job background jobs (retry, progress, permissions) and @Workflow DAG pipelines; framework adapters and the OpenAPI adapter (turn OpenAPI 3.x specs into MCP tools with auth, polling, transforms); plugins, plugin lifecycle hooks (before / after / around / stage), and the official plugins; instruction-only skills and skills that reference tools; and the hierarchical decorator system from @FrontMcp down to @App. Triggers: create a resource, build a prompt, write a provider, add an agent, job, workflow, plugin, adapter, or OpenAPI integration.'
+when_to_use: |
+  Trigger when creating or editing a non-tool FrontMCP component: a
+  *.resource.ts, *.prompt.ts, *.provider.ts, *.agent.ts, *.job.ts,
+  *.workflow.ts, *.plugin.ts, or *.skill.ts file, or adding @Resource, @Prompt,
+  @Provider, @Agent, @Job, @Workflow, a plugin, an adapter, or an OpenAPI
+  integration. For tools (*.tool.ts) use create-tool instead.
+paths: '**/*.resource.ts, **/*.prompt.ts, **/*.provider.ts, **/*.agent.ts, **/*.job.ts, **/*.workflow.ts, **/*.plugin.ts, **/*.skill.ts'
 tags: [router, development, tools, resources, prompts, agents, skills, guide]
 category: development
 targets: [all]
@@ -14,7 +21,7 @@ metadata:
 
 # FrontMCP Development Router
 
-Entry point for building MCP server components. This skill helps you find the right development skill based on what you want to build. It does not teach implementation details itself — it routes you to the specific skill that does.
+Entry point for building MCP server components. This skill helps you find the right development reference based on what you want to build. It does not teach implementation details itself — it routes you to the specific reference (under `references/`) that does.
 
 ## When to Use This Skill
 
@@ -26,7 +33,7 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ### Recommended
 
-- Looking up the canonical name of a development skill to install or search
+- Looking up the canonical name of a development reference to install or search
 - Comparing component types to decide which fits your use case
 - Understanding how tools, resources, prompts, agents, and skills relate to each other
 
@@ -36,7 +43,7 @@ Entry point for building MCP server components. This skill helps you find the ri
 - You need to configure server settings, not build components (see `frontmcp-config`)
 - You need to deploy or build, not develop (see `frontmcp-deployment`)
 
-> **Decision:** Use this skill when you need to figure out WHAT to build. Use the specific skill when you already know.
+> **Decision:** Use this skill when you need to figure out WHAT to build. Open the matching reference under `references/` directly when you already know.
 
 ## Prerequisites
 
@@ -46,40 +53,38 @@ Entry point for building MCP server components. This skill helps you find the ri
 
 ## Steps
 
-This is a router skill. The "steps" here are how to choose the right child skill, not how to implement a component.
+This is a router skill. The "steps" here are how to choose the right reference (a markdown file under `references/`), not how to implement a component.
 
 1. **Identify the component type** using the Scenario Routing Table below.
-2. **Open the matching skill** (e.g. `create-tool`, `create-resource`) and follow its Steps section.
-3. **Compose**, if needed: most non-trivial features need two or more components (e.g. tool + provider, resource + adapter). Read each child skill independently before wiring them together.
+2. **Open the matching reference** (e.g. `references/create-tool.md`, `references/create-resource.md`) and follow its Steps section.
+3. **Compose**, if needed: most non-trivial features need two or more components (e.g. tool + provider, resource + adapter). Read each reference independently before wiring them together.
 4. **Test before integration** (`frontmcp-testing`) — every component type has a unit-test recipe.
 
 ## Scenario Routing Table
 
-| Scenario                                                 | Skill                             | Description                                                                                   |
-| -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
-| Expose an executable action that AI clients can call     | `create-tool`                     | Class-based or function-style tools with Zod input/output validation                          |
-| Expose read-only data via a URI                          | `create-resource`                 | Static resources or URI template resources for dynamic data                                   |
-| Create a reusable conversation template or system prompt | `create-prompt`                   | Prompt entries with arguments and multi-turn message sequences                                |
-| Build an autonomous AI loop that orchestrates tools      | `create-agent`                    | Agent entries with LLM config, inner tools, and swarm handoff                                 |
-| Register shared services or configuration via DI         | `create-provider`                 | Dependency injection tokens, lifecycle hooks, factory providers                               |
-| Run a background task with progress and retries          | `create-job`                      | Job entries with attempt tracking, retry config, and progress                                 |
-| Chain multiple jobs into a sequential pipeline           | `create-workflow`                 | Workflow entries that compose jobs with data passing                                          |
-| Write instruction-only AI guidance (no code execution)   | `create-skill`                    | Skill entries with markdown instructions from files, strings, or URLs                         |
-| Write AI guidance that also orchestrates tools           | `create-skill-with-tools`         | Skill entries that combine instructions with registered tools                                 |
-| Look up any decorator signature or option                | `decorators-guide`                | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more           |
-| Overview of all official adapters                        | `official-adapters`               | Router to all adapter types; adapter vs plugin comparison                                     |
-| Integrate an external API via OpenAPI spec               | `openapi-adapter`                 | OpenapiAdapter with auth, polling, filtering, transforms, format resolution, $ref security    |
-| Use official plugins (caching, remember, feature flags)  | `official-plugins`                | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta) |
-| Connect to an external data source via a custom adapter  | `create-adapter`                  | Create custom adapters for external data sources                                              |
-| Configure LLM settings for an agent component            | `create-agent-llm-config`         | Configure LLM settings for agent components                                                   |
-| Add will/did/around lifecycle hooks to a plugin          | `create-plugin-hooks`             | Add lifecycle hooks to plugins (will/did/around)                                              |
-| Annotate tools with client hints for AI clients          | `create-tool-annotations`         | Add MCP tool annotations for client hints                                                     |
-| Define typed output schemas for tool responses           | `create-tool-output-schema-types` | Define typed output schemas for tools                                                         |
+| Scenario                                                                                                                                                                                        | Reference                                                      | Description                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Expose an executable action that AI clients can call (full surface: schemas, DI, errors, throttling, auth, availability, elicitation, UI widgets, annotations, examples metadata, registration) | **[`create-tool` (top-level skill)](../create-tool/SKILL.md)** | Single source of truth for everything inside `@Tool({...})`. Subsumes the former `create-tool`, `create-tool-annotations`, `create-tool-output-schema-types`, and `create-tool-ui` references. |
+| Expose read-only data via a URI                                                                                                                                                                 | `create-resource`                                              | Static resources or URI template resources for dynamic data                                                                                                                                    |
+| Create a reusable conversation template or system prompt                                                                                                                                        | `create-prompt`                                                | Prompt entries with arguments and multi-turn message sequences                                                                                                                                 |
+| Build an autonomous AI loop that orchestrates tools                                                                                                                                             | `create-agent`                                                 | Agent entries with LLM config, inner tools, and swarm handoff                                                                                                                                  |
+| Register shared services or configuration via DI                                                                                                                                                | `create-provider`                                              | Dependency injection tokens, lifecycle hooks, factory providers                                                                                                                                |
+| Run a background task with progress and retries                                                                                                                                                 | `create-job`                                                   | Job entries with attempt tracking, retry config, and progress                                                                                                                                  |
+| Chain multiple jobs into a sequential pipeline                                                                                                                                                  | `create-workflow`                                              | Workflow entries that compose jobs with data passing                                                                                                                                           |
+| Write instruction-only AI guidance (no code execution)                                                                                                                                          | `create-skill`                                                 | Skill entries with markdown instructions from files, strings, or URLs                                                                                                                          |
+| Write AI guidance that also orchestrates tools                                                                                                                                                  | `create-skill-with-tools`                                      | Skill entries that combine instructions with registered tools                                                                                                                                  |
+| Look up any decorator signature or option                                                                                                                                                       | `decorators-guide`                                             | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more                                                                                                            |
+| Overview of all official adapters                                                                                                                                                               | `official-adapters`                                            | Router to all adapter types; adapter vs plugin comparison                                                                                                                                      |
+| Integrate an external API via OpenAPI spec                                                                                                                                                      | `openapi-adapter`                                              | OpenapiAdapter with auth, polling, filtering, transforms, format resolution, $ref security                                                                                                     |
+| Use official plugins (caching, remember, feature flags)                                                                                                                                         | `official-plugins`                                             | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta)                                                                                                  |
+| Connect to an external data source via a custom adapter                                                                                                                                         | `create-adapter`                                               | Create custom adapters for external data sources                                                                                                                                               |
+| Configure LLM settings for an agent component                                                                                                                                                   | `create-agent-llm-config`                                      | Configure LLM settings for agent components                                                                                                                                                    |
+| Add will/did/around lifecycle hooks to a plugin                                                                                                                                                 | `create-plugin-hooks`                                          | Add lifecycle hooks to plugins (will/did/around)                                                                                                                                               |
 
 ## Recommended Reading Order
 
 1. **`decorators-guide`** — Start here to understand the full decorator landscape
-2. **`create-tool`** — The most common building block; learn tools first
+2. **[`create-tool`](../create-tool/SKILL.md)** — The most common building block (top-level skill — covers schemas, DI, errors, throttling, auth, UI widgets, annotations); learn tools first
 3. **`create-resource`** — Expose data alongside tools
 4. **`create-prompt`** — Add reusable conversation templates
 5. **`create-provider`** — Share services across tools and resources via DI
@@ -225,28 +230,9 @@ Each reference has matching examples under [`examples/<reference>/`](./examples/
 | [`directory-based-skill`](./examples/create-skill/directory-based-skill.md) | Advanced     | A skill loaded from a directory structure with SKILL.md frontmatter, plus file-based and URL-based instruction sources. |
 | [`parameterized-skill`](./examples/create-skill/parameterized-skill.md)     | Intermediate | A skill with customizable parameters, usage examples for AI guidance, and controlled visibility.                        |
 
-### `create-tool-annotations`
+### `create-tool` (migrated to top-level skill)
 
-| Example                                                                                    | Level        | Description                                                                                                                     |
-| ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| [`destructive-delete-tool`](./examples/create-tool-annotations/destructive-delete-tool.md) | Intermediate | Demonstrates annotating a tool that deletes data, enabling MCP clients to warn users before execution.                          |
-| [`readonly-query-tool`](./examples/create-tool-annotations/readonly-query-tool.md)         | Basic        | Demonstrates annotating a tool that only reads data, signaling to MCP clients that it has no side effects and is safe to retry. |
-
-### `create-tool-output-schema-types`
-
-| Example                                                                                                    | Level        | Description                                                                                                                                                    |
-| ---------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`primitive-and-media-outputs`](./examples/create-tool-output-schema-types/primitive-and-media-outputs.md) | Intermediate | Demonstrates using primitive string literals and media types as `outputSchema` for tools that return plain text, images, or multi-content arrays.              |
-| [`zod-raw-shape-output`](./examples/create-tool-output-schema-types/zod-raw-shape-output.md)               | Basic        | Demonstrates the recommended approach of using a Zod raw shape as `outputSchema` for structured, validated JSON output.                                        |
-| [`zod-schema-advanced-output`](./examples/create-tool-output-schema-types/zod-schema-advanced-output.md)   | Advanced     | Demonstrates using full Zod schema objects (not raw shapes) as `outputSchema`, including `z.object()`, `z.array()`, `z.union()`, and `z.discriminatedUnion()`. |
-
-### `create-tool`
-
-| Example                                                                                                  | Level        | Description                                                                                                    |
-| -------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
-| [`basic-class-tool`](./examples/create-tool/basic-class-tool.md)                                         | Basic        | A minimal tool using the class-based pattern with Zod input validation and output schema.                      |
-| [`tool-with-di-and-errors`](./examples/create-tool/tool-with-di-and-errors.md)                           | Intermediate | A tool that resolves a database service via DI and uses `this.fail()` for business-logic errors.               |
-| [`tool-with-rate-limiting-and-progress`](./examples/create-tool/tool-with-rate-limiting-and-progress.md) | Advanced     | A batch processing tool that uses rate limiting, concurrency control, progress notifications, and annotations. |
+The full `@Tool({...})` surface — including the former `create-tool-annotations`, `create-tool-output-schema-types`, and `create-tool-ui` references — now lives in the top-level [`create-tool`](../create-tool/SKILL.md) skill. See its [`examples/`](../create-tool/examples/) directory for 25 combination examples covering schemas, DI, errors, throttling, auth, availability, elicitation, UI widgets, annotations, examples metadata, and job hand-off.
 
 ### `create-workflow`
 
@@ -299,4 +285,4 @@ when a server has been configured to host this skill.
 ## Reference
 
 - [FrontMCP Overview](https://docs.agentfront.dev/frontmcp/fundamentals/overview)
-- Related skills: `create-tool`, `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `openapi-adapter`, `official-plugins`
+- Related skills: [`create-tool`](../create-tool/SKILL.md) (top-level), `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `openapi-adapter`, `official-plugins`

package/catalog/frontmcp-development/examples/create-provider/basic-database-provider.md

@@ -118,6 +118,20 @@ class MainApp {}
 - Consuming the provider in a tool via `this.get(DB_TOKEN)` with full type safety
 - Registering the factory in the `providers` array so tools can resolve it
 
+## When to promote this to a folder
+
+The flat `src/apps/main/providers/database.provider.ts` layout above is fine while the provider is a single class. The moment you add a `database.provider.spec.ts`, a `connection.ts` helper, or a config-loading module, promote it to its own folder:
+
+```text
+src/apps/main/providers/database/
+├── index.ts                       # barrel: re-exports the factory + DatabasePool class
+├── database.provider.ts           # AsyncProvider factory + DatabasePool class
+├── database.provider.spec.ts      # tests
+└── connection.ts                  # (optional) connection-setup helper
+```
+
+See [`create-provider` → File Layout](../../references/create-provider.md#file-layout) for the full convention.
+
 ## Related
 
 - See `create-provider` for configuration providers, HTTP API clients, and cache providers

package/catalog/frontmcp-development/examples/create-provider/config-and-api-providers.md

@@ -2,18 +2,40 @@
 name: config-and-api-providers
 reference: create-provider
 level: intermediate
-description: 'A configuration provider with readonly environment settings and an HTTP API client provider.'
+description: 'A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.'
 tags: [development, provider, config, api, providers]
 features:
   - 'A configuration provider using `readonly` properties from environment variables (sync construction)'
   - 'An API client provider that reads credentials in the constructor (no `onInit` — `@Provider` has no lifecycle hooks)'
+  - 'Folder-per-provider layout (`src/apps/main/providers/<slug>/`) with a barrel `index.ts` and a co-located `.provider.spec.ts`'
+  - 'Top-level `src/apps/main/providers/index.ts` barrel re-exporting each provider folder'
   - 'Registering providers at `@FrontMcp` level for server-wide sharing across all apps'
   - 'Separating token definitions from provider implementations for clean dependency boundaries'
 ---
 
 # Configuration and API Client Providers
 
-A configuration provider with readonly environment settings and an HTTP API client provider.
+A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.
+
+## File layout
+
+```text
+src/apps/main/
+├── tokens.ts                                # shared token + interface definitions
+├── index.ts                                 # @App / @FrontMcp registration
+└── providers/
+    ├── index.ts                             # top-level barrel
+    ├── config/
+    │   ├── index.ts                         # barrel: ConfigProvider
+    │   ├── config.provider.ts               # @Provider class
+    │   └── config.provider.spec.ts          # tests
+    └── api-client/
+        ├── index.ts                         # barrel: ApiClientProvider
+        ├── api-client.provider.ts           # @Provider class
+        └── api-client.provider.spec.ts      # tests
+```
+
+Each provider lives in its own subfolder with a barrel — cross-provider imports go through the barrel (`from '../config'`), never reaching into another provider's implementation file.
 
 ## Code
 
@@ -38,13 +60,13 @@ export const API_TOKEN: Token<ApiClient> = Symbol('ApiClient');
 ```
 
 ```typescript
-// src/apps/main/providers/config.provider.ts
+// src/apps/main/providers/config/config.provider.ts
 import { Provider } from '@frontmcp/sdk';
 
-import type { AppConfig } from '../tokens';
+import type { AppConfig } from '../../tokens';
 
 @Provider({ name: 'ConfigProvider' })
-class ConfigProvider implements AppConfig {
+export class ConfigProvider implements AppConfig {
   readonly apiBaseUrl = process.env.API_BASE_URL ?? 'https://api.example.com';
   readonly maxRetries = Number(process.env.MAX_RETRIES ?? 3);
   readonly debug = process.env.DEBUG === 'true';
@@ -52,13 +74,31 @@ class ConfigProvider implements AppConfig {
 ```
 
 ```typescript
-// src/apps/main/providers/api-client.provider.ts
+// src/apps/main/providers/config/index.ts
+export { ConfigProvider } from './config.provider';
+```
+
+```typescript
+// src/apps/main/providers/config/config.provider.spec.ts
+import { ConfigProvider } from './config.provider';
+
+describe('ConfigProvider', () => {
+  it('reads apiBaseUrl from env with a default fallback', () => {
+    const provider = new ConfigProvider();
+    expect(provider.apiBaseUrl).toBeDefined();
+    expect(typeof provider.apiBaseUrl).toBe('string');
+  });
+});
+```
+
+```typescript
+// src/apps/main/providers/api-client/api-client.provider.ts
 import { Provider } from '@frontmcp/sdk';
 
-import type { ApiClient } from '../tokens';
+import type { ApiClient } from '../../tokens';
 
 @Provider({ name: 'ApiClientProvider' })
-class ApiClientProvider implements ApiClient {
+export class ApiClientProvider implements ApiClient {
   // `@Provider` has no `onInit` lifecycle hook — read env in the constructor.
   // First instantiation throws synchronously on missing config (fail fast).
   private readonly baseUrl: string;
@@ -92,10 +132,44 @@ class ApiClientProvider implements ApiClient {
 }
 ```
 
+```typescript
+// src/apps/main/providers/api-client/index.ts
+export { ApiClientProvider } from './api-client.provider';
+```
+
+```typescript
+// src/apps/main/providers/api-client/api-client.provider.spec.ts
+import { ApiClientProvider } from './api-client.provider';
+
+describe('ApiClientProvider', () => {
+  const origEnv = { ...process.env };
+  afterEach(() => {
+    process.env = { ...origEnv };
+  });
+
+  it('throws fast when API_URL or API_KEY is missing', () => {
+    delete process.env.API_URL;
+    delete process.env.API_KEY;
+    expect(() => new ApiClientProvider()).toThrow(/API_URL and API_KEY/);
+  });
+});
+```
+
+```typescript
+// src/apps/main/providers/index.ts
+// Top-level barrel — re-exports each provider folder so importers can do
+// `import { ConfigProvider, ApiClientProvider } from './providers'`.
+export * from './config';
+export * from './api-client';
+```
+
 ```typescript
 // src/index.ts
 import { FrontMcp } from '@frontmcp/sdk';
 
+import { MainApp } from './apps/main';
+import { ApiClientProvider, ConfigProvider } from './apps/main/providers';
+
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MainApp],
@@ -108,9 +182,11 @@ class MyServer {}
 
 - A configuration provider using `readonly` properties from environment variables (sync construction)
 - An API client provider that reads credentials in the constructor (no `onInit` — `@Provider` has no lifecycle hooks)
+- Folder-per-provider layout (`src/apps/main/providers/<slug>/`) with a barrel `index.ts` and a co-located `.provider.spec.ts`
+- Top-level `src/apps/main/providers/index.ts` barrel re-exporting each provider folder
 - Registering providers at `@FrontMcp` level for server-wide sharing across all apps
 - Separating token definitions from provider implementations for clean dependency boundaries
 
 ## Related
 
-- See `create-provider` for cache providers, lifecycle details, and the `tryGet()` safe access pattern
+- See `create-provider` for the [File Layout](../../references/create-provider.md#file-layout) section, cache providers, lifecycle details, and the `tryGet()` safe access pattern

package/catalog/frontmcp-development/references/create-job.md

@@ -418,7 +418,9 @@ class DataApp {}
 
 ### Enabling the Jobs System
 
-Jobs require a persistent store for state management. Enable the jobs system in `@FrontMcp` configuration.
+**Auto-enable (issue #408):** declaring any `@App({ jobs: [...] })` (or `workflows: [...]`) is enough — the jobs subsystem comes up with in-memory stores by default and the management tools (`execute_job`, `list_jobs`, `get_job_status`, `register_job`, `remove_job`) are registered automatically so agents can invoke them. No `@FrontMcp({ jobs: { enabled: true } })` is required for the happy path.
+
+**When to configure `@FrontMcp({ jobs })` explicitly:** override the in-memory default with persistent storage (Redis recommended for multi-replica HA) so job state, progress, logs, and outputs survive retries and server restarts.
 
 ```typescript
 import { FrontMcp } from '@frontmcp/sdk';
@@ -426,8 +428,9 @@ import { FrontMcp } from '@frontmcp/sdk';
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [DataApp],
+  // `enabled: true` is implied by `@App({ jobs })`. Set explicitly only to
+  // configure store, or set to `false` to opt out and suppress the tools.
   jobs: {
-    enabled: true,
     store: {
       redis: {
         provider: 'redis',
@@ -441,7 +444,36 @@ import { FrontMcp } from '@frontmcp/sdk';
 class MyServer {}
 ```
 
-The store persists job state, progress, logs, and outputs across retries and server restarts. Redis is recommended for production. Without `jobs.enabled: true`, registered jobs will not be activated.
+Setting `jobs: { enabled: false }` is an explicit opt-out — declared jobs will NOT be activated and the framework logs a warning so the configuration mismatch is loud.
+
+### Calling Jobs from an Agent
+
+Once jobs are registered, the SDK exposes five MCP tools (snake_case per ecosystem convention; hyphen aliases like `execute-job` keep working with a deprecation log line for one release):
+
+| Tool             | Purpose                                                                  |
+| ---------------- | ------------------------------------------------------------------------ |
+| `list_jobs`      | List registered jobs with optional `tags` / `labels` / `query` filters   |
+| `execute_job`    | Execute a registered job by name (`{ name, input?, background? }`)       |
+| `get_job_status` | Get the run state for a `runId` returned by `execute_job`                |
+| `register_job`   | Register a dynamic job at runtime (sandboxed; `hideFromDiscovery: true`) |
+| `remove_job`     | Remove a dynamic job by name (`hideFromDiscovery: true`)                 |
+
+Workflows expose a parallel set: `list_workflows`, `execute_workflow`, `get_workflow_status`, `register_workflow`, `remove_workflow`.
+
+For finer-grained control (e.g. omit `register_job` / `remove_job` in production), opt out of auto-registration by importing the tool classes manually:
+
+```typescript
+import { App, ExecuteJobTool, GetJobStatusTool, ListJobsTool } from '@frontmcp/sdk';
+
+@App({
+  name: 'data-app',
+  jobs: [GenerateReportJob],
+  tools: [ExecuteJobTool, ListJobsTool, GetJobStatusTool], // omit register/remove
+})
+class DataApp {}
+```
+
+The same classes are also reachable via the subpath `@frontmcp/sdk/job/tools` and `@frontmcp/sdk/workflow/tools` for bundlers that prefer narrower imports.
 
 ## Nx Generator
 
@@ -603,7 +635,9 @@ class DataServer {}
 
 ### Runtime
 
-- [ ] `jobs.enabled: true` is set in `@FrontMcp` configuration with a store
+- [ ] Jobs subsystem is active — either implicitly via `@App({ jobs: [...] })`
+      (auto-enable, issue #408) or explicitly via `@FrontMcp({ jobs: { store: { ... } } })`
+      when overriding the in-memory default
 - [ ] Job executes and returns output matching `outputSchema`
 - [ ] Progress is reported and queryable during execution
 - [ ] Retry fires with correct backoff delays on transient failures
@@ -611,13 +645,13 @@ class DataServer {}
 
 ## Troubleshooting
 
-| Problem                    | Cause                                           | Solution                                                                     |
-| -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| Job not activated          | `jobs.enabled` not set to `true` in `@FrontMcp` | Add `jobs: { enabled: true, store: { ... } }` to `@FrontMcp` config          |
-| Job fails without retrying | No `retry` policy configured                    | Add `retry: { maxAttempts: 3, backoffMs: 2000 }` to `@Job` options           |
-| Progress not visible       | Not calling `this.progress()` during execution  | Add `this.progress(pct, total, message)` calls at each stage                 |
-| Job times out unexpectedly | Default 5-minute timeout too short              | Set `timeout` in `@Job` to a higher value (e.g., `600000` for 10 minutes)    |
-| Permission denied error    | User lacks required roles or scopes             | Verify user has one of the `roles` and all `scopes` defined in `permissions` |
+| Problem                    | Cause                                                                                       | Solution                                                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Job not activated          | `@App` doesn't declare `jobs: [...]` AND `@FrontMcp({ jobs: { enabled: true } })` isn't set | Add the job class to `@App({ jobs: [...] })` (auto-enables) OR set `@FrontMcp({ jobs: { enabled: true, store: { ... } } })` |
+| Job fails without retrying | No `retry` policy configured                                                                | Add `retry: { maxAttempts: 3, backoffMs: 2000 }` to `@Job` options                                                          |
+| Progress not visible       | Not calling `this.progress()` during execution                                              | Add `this.progress(pct, total, message)` calls at each stage                                                                |
+| Job times out unexpectedly | Default 5-minute timeout too short                                                          | Set `timeout` in `@Job` to a higher value (e.g., `600000` for 10 minutes)                                                   |
+| Permission denied error    | User lacks required roles or scopes                                                         | Verify user has one of the `roles` and all `scopes` defined in `permissions`                                                |
 
 ## Examples
 

package/catalog/frontmcp-development/references/create-provider.md

@@ -164,6 +164,73 @@ if (!db) {
 }
 ```
 
+## File Layout
+
+Once a provider grows past a single class, a flat `src/providers/<slug>.provider.ts` becomes ambiguous: helpers, internal types, schema fragments, and the spec file all need somewhere to go. The recommended convention is **one folder per provider**, co-locating the class, the spec, an optional barrel, and any helpers:
+
+```text
+src/providers/<provider-slug>/
+├── index.ts                            # barrel: re-exports class, factory, public types
+├── <provider-slug>.provider.ts         # @Provider class and/or AsyncProvider factory
+├── <provider-slug>.provider.spec.ts    # unit tests
+├── types.ts                            # (optional) internal types / token interfaces
+└── <helper>.ts (+ .spec.ts)            # (optional) per-provider helpers
+```
+
+Plus a top-level `src/providers/index.ts` barrel re-exporting each subfolder:
+
+```typescript
+// src/providers/index.ts
+export * from './task-store';
+export * from './config';
+export * from './redis';
+```
+
+### Naming rules
+
+- **Folder slug**: `kebab-case`, matches the provider's primary purpose (`task-store`, `redis`, `api-client`).
+- **Class file**: `<slug>.provider.ts` — matches the in-tree demo-app convention (`apps/demo/src/apps/expenses/providers/redis.provider.ts`) and what the Nx generator emits.
+- **Spec file**: `<slug>.provider.spec.ts` — co-located with source per the repo's `.spec.ts` convention (CLAUDE.md).
+- **Barrel**: `index.ts`, re-exporting the class, the `AsyncProvider` factory (if any), and any public types/tokens.
+
+### Single-file vs folder — when to fold
+
+A trivial provider (e.g. a `Map`-based cache, a pure DTO with no helpers) does NOT need its own folder; promote to a folder as soon as the provider grows. Use this rubric:
+
+| Provider shape                                         | Layout                                                  | Why                                                                            |
+| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Pure DTO (e.g. `extends Map`, no methods, no helpers)  | Single file `<slug>.provider.ts` under `src/providers/` | A folder for a 5-line class is over-architected                                |
+| Provider with a spec file                              | Folder                                                  | Keeps source and spec adjacent; matches CLAUDE.md `.spec.ts` rule              |
+| Provider with helpers, types, or schema fragments      | Folder                                                  | Helpers/types are private to the provider; folder boundary makes that explicit |
+| `AsyncProvider({ useFactory })` with non-trivial setup | Folder                                                  | Factory + class + setup helpers cluster naturally                              |
+| Multiple related providers sharing helpers             | Folder per provider + sibling `_shared/` folder         | Avoids leaking helpers into the top-level `providers/` namespace               |
+
+### Cross-provider imports
+
+Cross-provider imports go through the **subfolder barrel**, not into another provider's internals:
+
+<!-- prettier-ignore -->
+```typescript
+// ✅ Good — imports through the subfolder barrel
+import { TaskStoreProvider } from '../task-store';
+
+// ❌ Bad — top-level barrel for sibling imports causes circular-init churn
+import { TaskStoreProvider } from '..';
+// ❌ Bad — reaches into another provider's implementation file
+import { TaskStoreProvider } from '../task-store/task-store.provider';
+```
+
+Tool → provider imports follow the same rule:
+
+```typescript
+// ✅ Good — tool imports the provider's public surface from its barrel
+import { TaskStoreProvider } from '../../providers/task-store';
+```
+
+### Same convention for tools and resources
+
+The folder layout applies to `create-tool` and `create-resource` too. Once a tool grows a `<slug>.schema.ts` or a resource grows a content helper, promote it to `src/tools/<slug>/` or `src/resources/<slug>/` with the same barrel + spec layout. (Tracked separately in issue #405 for `create-tool`.)
+
 ## Common Provider Patterns
 
 ### Configuration Provider
@@ -258,6 +325,8 @@ class CacheProvider extends Map<string, unknown> {
 nx generate @frontmcp/nx:provider my-provider --project=my-app
 ```
 
+The generator currently writes a single `<slug>.provider.ts` directly into `src/providers/`. Promote it to the folder layout above as soon as you add a spec file or helpers — see [File Layout](#file-layout).
+
 ## Verification
 
 ```bash
@@ -270,13 +339,15 @@ frontmcp dev
 
 ## Common Patterns
 
-| Pattern            | Correct                                                                | Incorrect                                        | Why                                                                                         |
-| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| Token definition   | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)      | `const DB = 'database'` (string literal)         | Typed `Token<T>` enables compile-time type checking on `this.get()`                         |
-| DI resolution      | `this.get(TOKEN)` with error handling                                  | `this.tryGet(TOKEN)!` with non-null assertion    | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures           |
-| Lifecycle          | `AsyncProvider({ useFactory })` for async setup; constructor for sync  | Using `onInit()` / `onDestroy()` lifecycle hooks | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution |
-| Registration scope | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped | Registering same provider in multiple apps       | Server-scoped providers are shared; duplicating causes multiple instances                   |
-| Config provider    | `readonly` properties from `process.env`                               | Mutable properties that change at runtime        | Providers are singletons; mutable state can cause race conditions                           |
+| Pattern               | Correct                                                                                           | Incorrect                                                               | Why                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Token definition      | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)                                 | `const DB = 'database'` (string literal)                                | Typed `Token<T>` enables compile-time type checking on `this.get()`                          |
+| DI resolution         | `this.get(TOKEN)` with error handling                                                             | `this.tryGet(TOKEN)!` with non-null assertion                           | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures            |
+| Lifecycle             | `AsyncProvider({ useFactory })` for async setup; constructor for sync                             | Using `onInit()` / `onDestroy()` lifecycle hooks                        | `@Provider` has no lifecycle hooks; `AsyncProvider` factories are awaited before resolution  |
+| Registration scope    | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped                            | Registering same provider in multiple apps                              | Server-scoped providers are shared; duplicating causes multiple instances                    |
+| Config provider       | `readonly` properties from `process.env`                                                          | Mutable properties that change at runtime                               | Providers are singletons; mutable state can cause race conditions                            |
+| File layout           | `src/providers/<slug>/` folder with `index.ts` + `<slug>.provider.ts` + `<slug>.provider.spec.ts` | Flat `src/providers/<slug>.provider.ts` once helpers or a spec exist    | Co-locates source, tests, helpers; barrel hides internals — see [File Layout](#file-layout)  |
+| Cross-provider import | `import { TaskStoreProvider } from '../task-store'` (subfolder barrel)                            | `import { TaskStoreProvider } from '../task-store/task-store.provider'` | Subfolder barrel hides internals; reaching past it couples consumers to implementation files |
 
 ## Verification Checklist
 
@@ -287,6 +358,7 @@ frontmcp dev
 - [ ] Provider (class or `AsyncProvider` factory) is registered in `providers` array of `@App` or `@FrontMcp`
 - [ ] Sync setup happens in the constructor (throws fast on missing config)
 - [ ] Async setup uses `AsyncProvider({ useFactory })`; the framework awaits it before resolution
+- [ ] Each provider lives in its own `src/providers/<slug>/` folder once it has a spec, helpers, or internal types (single-file is fine for trivial providers — see the [File Layout](#file-layout) rubric)
 
 ### Runtime
 
@@ -312,7 +384,7 @@ frontmcp dev
 | Example                                                                               | Level        | Description                                                                                                                                   |
 | ------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`basic-database-provider`](../examples/create-provider/basic-database-provider.md)   | Basic        | A provider that manages a database connection pool, bound through `AsyncProvider({ useFactory })` so the pool is opened before any tool runs. |
-| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider with readonly environment settings and an HTTP API client provider.                                                  |
+| [`config-and-api-providers`](../examples/create-provider/config-and-api-providers.md) | Intermediate | A configuration provider and an HTTP API client provider, organized as one folder per provider with co-located specs and barrels.             |
 
 > See all examples in [`examples/create-provider/`](../examples/create-provider/)
 

package/catalog/frontmcp-development/references/create-skill-with-tools.md

@@ -462,6 +462,37 @@ nx generate @frontmcp/nx:skill-dir
 
 The class generator creates the skill file, spec file, and updates barrel exports. The directory generator creates the full directory structure ready for `skillDir()`.
 
+## Installing on a User's Machine
+
+Tool-enabled skills install the same way as instruction-only skills —
+the tools they reference are exposed through the same MCP server, so
+copying the `SKILL.md` (with the decorator metadata in its frontmatter)
+under `.claude/skills/<name>/` is all Claude Code needs to load it.
+
+```bash
+# Install one named skill from a local project entry
+frontmcp skills install deploy-service --from-entry src/main.ts -p claude
+
+# Install every @Skill the project exposes
+frontmcp skills install --from-entry src/main.ts --all -p claude
+
+# Install from a published package (resolves the package main entry)
+frontmcp skills install --from-package my-devops-server --all -p claude
+```
+
+The CLI bundles the entry, enumerates `@Skill` entries via the SDK's
+in-memory client, and copies each skill's `SKILL.md` and resource
+directories. When a skill declares `allowedTools` in its decorator, that
+list ends up in the synthesized SKILL.md frontmatter so Claude Code
+pre-approves those tools during the skill session. See
+`frontmcp-skills-usage` for the full selector matrix, and `create-skill`
+for the analogous note on instruction-only skills.
+
+> Shipping slash commands alongside the skills? Use the full per-bin
+> install instead: `my-devops-server install -p claude` writes the
+> plugin manifest, `commands/` directory, and `skills/` directory in a
+> single pass.
+
 ## HTTP Endpoints for Skill Discovery
 
 When skills have `visibility` set to `'http'` or `'both'`, they are discoverable via HTTP endpoints: