@frontmcp/skills 0.0.1 → 1.0.0-beta.9

package/catalog/{development/create-workflow/SKILL.md → frontmcp-development/references/create-workflow.md}

@@ -1,28 +1,28 @@
----
-name: create-workflow
-description: Create multi-step workflows that connect jobs into managed execution pipelines with dependencies and conditions. Use when orchestrating sequential or parallel job execution.
-tags: [workflow, pipeline, orchestration, steps, jobs]
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/workflows
----
-
 # Creating Workflows
 
 Workflows connect multiple jobs into managed execution pipelines with step dependencies, conditions, and triggers. A workflow defines a directed acyclic graph (DAG) of steps where each step runs a named job, and the framework handles ordering, parallelism, error propagation, and trigger management.
 
-## When to Use @Workflow
+## When to Use This Skill
+
+### Must Use
+
+- Orchestrating multiple jobs in a defined order with explicit step dependencies (e.g., build then test then deploy)
+- Building execution pipelines that require conditional branching, parallel fan-out, or diamond dependency patterns
+- Defining webhook- or event-triggered multi-step automation that the framework manages end to end
+
+### Recommended
 
-Use `@Workflow` when you need to orchestrate multiple jobs in a defined order with dependencies between them. Examples include:
+- CI/CD pipelines, data-processing ETL flows, or approval chains that combine three or more jobs
+- Multi-stage provisioning sequences where steps need `continueOnError` or per-step retry policies
+- Replacing hand-rolled orchestration code with a declarative DAG of job steps
 
-- CI/CD pipelines (build, test, deploy)
-- Data processing pipelines (extract, transform, load, verify)
-- Approval workflows (submit, review, approve, execute)
-- Multi-stage provisioning (create resources, configure, validate, notify)
+### Skip When
 
-If you only need a single background task, use a `@Job` instead. If you need real-time sequential tool calls guided by an AI, use a `@Skill`.
+- You only need a single background task with no inter-step dependencies (see `create-job`)
+- You need real-time, AI-guided sequential tool calls rather than pre-declared steps (see `create-skill-with-tools`)
+- You are building a conversational prompt template with no execution logic (see `create-prompt`)
+
+> **Decision:** Use this skill when you need a declarative, multi-step pipeline of jobs with dependency ordering, conditions, and managed error propagation.
 
 ## Class-Based Pattern
 
@@ -707,3 +707,45 @@ class CiApp {}
 })
 class CiServer {}
 ```
+
+## Common Patterns
+
+| Pattern           | Correct                                                            | Incorrect                                                          | Why                                                                             |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Step dependencies | `dependsOn: ['build', 'test']` (array of step IDs)                 | `dependsOn: 'build'` (plain string)                                | `dependsOn` expects a `string[]`, not a single string                           |
+| Dynamic input     | `input: (steps) => ({ artifact: steps.get('build').outputs.url })` | `input: { artifact: buildResult.url }` (captured closure variable) | Static objects cannot reference previous step outputs; use the callback form    |
+| Conditional steps | `condition: (steps) => steps.get('test').state === 'completed'`    | `condition: (steps) => steps.get('test').outputs` (truthy check)   | Always check `.state` explicitly; outputs can be truthy even on partial failure |
+| Job registration  | Register all referenced jobs in the `jobs` array of `@App`         | Declare `jobName` in steps without registering the job class       | Steps reference jobs by name; unregistered jobs cause runtime lookup failures   |
+| Workflow trigger  | Set `trigger: 'webhook'` and provide `webhook: { path, secret }`   | Set `trigger: 'webhook'` without a `webhook` config object         | Webhook trigger requires the `webhook` configuration block for path and secret  |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@Workflow` decorator has `name` and at least one step in `steps`
+- [ ] Every `jobName` in steps matches a registered `@Job` name
+- [ ] `dependsOn` arrays reference valid step `id` values within the same workflow
+- [ ] No circular dependencies exist in the step DAG
+
+### Runtime
+
+- [ ] Workflow appears in the server's workflow registry after startup
+- [ ] Steps with no dependencies execute in parallel (up to `maxConcurrency`)
+- [ ] Conditional steps are correctly skipped or executed based on prior step results
+- [ ] `continueOnError: true` steps allow downstream steps to proceed on failure
+- [ ] Webhook-triggered workflows respond to incoming HTTP requests
+
+## Troubleshooting
+
+| Problem                                             | Cause                                                          | Solution                                                                                           |
+| --------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Step never executes                                 | `dependsOn` references a step ID that does not exist           | Verify all `dependsOn` entries match actual step `id` values in the workflow                       |
+| Workflow fails at startup with "job not found"      | `jobName` references an unregistered job                       | Add the job class to the `jobs` array in `@App` before registering the workflow                    |
+| Dynamic `input` callback receives undefined outputs | Dependent step was skipped or failed without `continueOnError` | Add a `condition` guard that checks `steps.get(id).state === 'completed'` before accessing outputs |
+| Webhook trigger does not fire                       | Missing or mismatched `webhook.secret`                         | Ensure `webhook.secret` matches the sender's HMAC secret and `webhook.path` is correct             |
+| Workflow exceeds timeout                            | Total step execution time exceeds the default 600000 ms        | Increase `timeout` at the workflow level or add per-step `timeout` overrides                       |
+
+## Reference
+
+- [Workflows Documentation](https://docs.agentfront.dev/frontmcp/servers/workflows)
+- Related skills: `create-job`, `create-skill-with-tools`, `create-tool`, `multi-app-composition`

package/catalog/{development/decorators-guide/SKILL.md → frontmcp-development/references/decorators-guide.md}

@@ -1,21 +1,10 @@
----
-name: decorators-guide
-description: Complete reference for all FrontMCP decorators and when to use each one. Use when choosing between decorators, understanding the architecture, or looking up decorator signatures.
-tags: [decorators, reference, architecture, guide]
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview
----
-
 # FrontMCP Decorators - Complete Reference
 
 ## Architecture Overview
 
 FrontMCP uses a hierarchical decorator system. The nesting order is:
 
-```
+```text
 @FrontMcp          (server root)
   +-- @App         (application module)
        +-- @Tool           (MCP tool)
@@ -35,6 +24,30 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 
 ---
 
+## When to Use This Skill
+
+### Must Use
+
+- You are building a new FrontMCP server and need to choose the correct decorator for each component
+- You are reviewing or debugging decorator configuration and need to verify field names, types, or nesting hierarchy
+- You are onboarding to the FrontMCP codebase and need a single reference for the full decorator architecture
+
+### Recommended
+
+- You are adding a new capability (tool, resource, prompt, agent, skill) to an existing server and want to confirm the correct decorator signature
+- You are designing a plugin or adapter and need to understand how it integrates with the decorator hierarchy
+- You are refactoring an app's module structure and need to verify which decorators belong in `@App` vs `@FrontMcp`
+
+### Skip When
+
+- You only need to write business logic inside an existing tool or resource (see `create-tool` reference)
+- You are configuring authentication or session management without changing decorators (see `configure-auth` reference)
+- You are working on CI/CD, deployment, or infrastructure that does not involve decorator choices
+
+> **Decision:** Use this skill whenever you need to look up, choose, or validate a FrontMCP decorator -- skip it when the decorator is already chosen and you are only implementing internal logic.
+
+---
+
 ## 1. @FrontMcp
 
 **Purpose:** Declares the root MCP server and its global configuration.
@@ -43,27 +56,28 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 
 **Key fields:**
 
-| Field           | Description                                         |
-| --------------- | --------------------------------------------------- |
-| `info`          | Server name, version, and description               |
-| `apps`          | Array of `@App` classes to mount                    |
-| `redis?`        | Redis connection options                            |
-| `plugins?`      | Global plugins                                      |
-| `providers?`    | Global DI providers                                 |
-| `tools?`        | Standalone tools (outside apps)                     |
-| `resources?`    | Standalone resources                                |
-| `skills?`       | Standalone skills                                   |
-| `skillsConfig?` | Skills feature configuration (enabled, cache, auth) |
-| `transport?`    | Transport type (stdio, sse, streamable-http)        |
-| `http?`         | HTTP server options (port, host, cors)              |
-| `logging?`      | Logging configuration                               |
-| `elicitation?`  | Elicitation store config                            |
-| `sqlite?`       | SQLite storage config                               |
-| `pubsub?`       | Pub/sub configuration                               |
-| `jobs?`         | Job scheduler config                                |
-| `throttle?`     | Rate limiting config                                |
-| `pagination?`   | Pagination defaults                                 |
-| `ui?`           | UI configuration                                    |
+| Field           | Description                                                                     |
+| --------------- | ------------------------------------------------------------------------------- |
+| `info`          | Server name, version, and description                                           |
+| `apps`          | Array of `@App` classes to mount                                                |
+| `redis?`        | Redis connection options                                                        |
+| `plugins?`      | Global plugins                                                                  |
+| `providers?`    | Global DI providers                                                             |
+| `tools?`        | Standalone tools (outside apps)                                                 |
+| `resources?`    | Standalone resources                                                            |
+| `skills?`       | Standalone skills                                                               |
+| `skillsConfig?` | Skills feature configuration (enabled, cache, auth)                             |
+| `transport?`    | Transport preset ('modern', 'legacy', 'stateless-api', 'full') or config object |
+| `auth?`         | Authentication mode and OAuth configuration (AuthOptionsInput)                  |
+| `http?`         | HTTP server options (port, host, cors)                                          |
+| `logging?`      | Logging configuration                                                           |
+| `elicitation?`  | Elicitation store config                                                        |
+| `sqlite?`       | SQLite storage config                                                           |
+| `pubsub?`       | Pub/sub configuration                                                           |
+| `jobs?`         | Job scheduler config                                                            |
+| `throttle?`     | Rate limiting config                                                            |
+| `pagination?`   | Pagination defaults                                                             |
+| `ui?`           | UI configuration                                                                |
 
 ```typescript
 import { FrontMcp } from '@frontmcp/sdk';
@@ -71,7 +85,7 @@ import { FrontMcp } from '@frontmcp/sdk';
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MainApp],
-  transport: 'streamable-http',
+  transport: 'modern', // Valid presets: 'modern', 'legacy', 'stateless-api', 'full'
   http: { port: 3000 },
   plugins: [RememberPlugin],
   skillsConfig: { enabled: true },
@@ -596,3 +610,78 @@ class AuditHooks {
 | `@Job`                      | `JobContext`      | `@App.jobs`      | Background task          |
 | `@Workflow`                 | -                 | `@App.workflows` | Multi-step orchestration |
 | `@Will/@Did/@Stage/@Around` | -                 | Entry class      | Lifecycle hooks          |
+
+---
+
+## Common Patterns
+
+| Pattern                     | Correct                                                                       | Incorrect                                                                    | Why                                                                                                                                                        |
+| --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Grouping tools into modules | Place tools inside `@App({ tools: [...] })`                                   | Register tools directly in `@FrontMcp({ tools: [...] })` for large servers   | Apps provide logical grouping, scoped providers, and isolation; standalone tools in `@FrontMcp` are only appropriate for small servers or global utilities |
+| Exposing data to the LLM    | Use `@Resource` for fixed URIs, `@ResourceTemplate` for parameterized URIs    | Using `@Tool` to return static data that never changes                       | Resources are the MCP-standard way to expose readable data; tools are for actions with side effects or dynamic computation                                 |
+| Cross-cutting concerns      | Create a `@Plugin` with providers and context extensions                      | Adding logging/caching logic directly inside every tool's `execute()` method | Plugins centralize shared behavior, reduce duplication, and can be reused across servers                                                                   |
+| Background processing       | Use `@Job` with a cron schedule for recurring work                            | Using `setTimeout` or manual polling inside a tool                           | Jobs integrate with the scheduler, support persistence, and are visible in server diagnostics                                                              |
+| Multi-step orchestration    | Use `@Workflow` with ordered steps referencing `@Job` classes                 | Chaining multiple tool calls manually from the LLM                           | Workflows provide built-in ordering, error handling, and rollback semantics                                                                                |
+| Injecting services          | Use `@Provider` with `useFactory`/`useClass` and access via `this.get(Token)` | Importing singletons directly or using global state                          | DI providers support testability, lifecycle management, and per-scope isolation                                                                            |
+
+---
+
+## Verification Checklist
+
+### Structure
+
+- [ ] Server has exactly one `@FrontMcp` decorated class
+- [ ] Every `@App` is listed in the `@FrontMcp({ apps: [...] })` array
+- [ ] Each tool, resource, prompt, agent, and skill is registered in an `@App` (or in `@FrontMcp` for standalone use)
+
+### Decorator Fields
+
+- [ ] Every `@Tool` has `name`, `description`, and `inputSchema` defined
+- [ ] Every `@Resource` has `name` and `uri` with a valid scheme (e.g., `config://`, `file://`)
+- [ ] Every `@ResourceTemplate` has `uriTemplate` with `{param}` placeholders matching the `read()` params argument
+- [ ] Every `@Prompt` has `name` and at least one argument when it accepts input
+- [ ] Every `@Agent` has `name`, `description`, and `llm` configuration
+
+### Inheritance
+
+- [ ] Tool classes extend `ToolContext` and implement `execute()`
+- [ ] Prompt classes extend `PromptContext` and implement `execute()`
+- [ ] Resource classes extend `ResourceContext` and implement `read()`
+- [ ] Agent classes extend `AgentContext` and implement `execute()`
+- [ ] Job classes extend `JobContext` and implement `execute()`
+
+### Hooks
+
+- [ ] Hook flow strings match valid flows (e.g., `tools:call-tool`, `resources:read-resource`)
+- [ ] `@Around` hooks call `await next()` to continue the chain (unless intentionally short-circuiting)
+- [ ] Hooks do not mutate `rawInput` -- use `ctx.state.set()` for flow state
+
+### DI and Plugins
+
+- [ ] All `@Provider` entries specify exactly one of `useClass`, `useValue`, or `useFactory`
+- [ ] Plugins are registered in `@App({ plugins: [...] })` or `@FrontMcp({ plugins: [...] })`
+- [ ] Context extensions installed by plugins match the module augmentation declarations
+
+---
+
+## Troubleshooting
+
+| Problem                                            | Cause                                                                                                 | Solution                                                                                                                            |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Tool does not appear in `tools/list` MCP response  | Tool class is not registered in any `@App({ tools: [...] })` or `@FrontMcp({ tools: [...] })`         | Add the tool class to the `tools` array of the appropriate `@App` or `@FrontMcp` decorator                                          |
+| `this.get(Token)` throws `DependencyNotFoundError` | The provider for that token is not registered or is registered in a different app scope               | Add a `@Provider` for the token in the same `@App` or in `@FrontMcp({ providers: [...] })` for global access                        |
+| Resource returns 404 / `ResourceNotFoundError`     | The `uri` in `@Resource` does not match the requested URI, or `uriTemplate` parameters are misaligned | Verify the URI string exactly matches what the client requests; for templates, confirm `{param}` names match                        |
+| Hook never fires                                   | The `flow` string in `@Will`/`@Did`/`@Around`/`@Stage` does not match any registered flow             | Check the flow string against valid flows (e.g., `tools:call-tool`, `resources:read-resource`, `resources:list-resources`)          |
+| Plugin context extension is `undefined` at runtime | The plugin's `installContextExtension` function was not called, or module augmentation is missing     | Ensure the plugin is registered and its context extension function runs at startup; verify the `declare module` augmentation exists |
+| Agent `execute()` returns empty result             | LLM configuration is missing or invalid (wrong model name, missing API key)                           | Verify `llm.model` and `llm.provider` in `@Agent`, and ensure the provider API key is set in environment variables                  |
+
+---
+
+## Reference
+
+- **Official docs:** [FrontMCP Decorators Overview](https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview)
+- **Related skills:**
+  - `create-tool` -- step-by-step guide for building tools with `@Tool` and `ToolContext`
+  - `create-resource` -- patterns for `@Resource` and `@ResourceTemplate` usage
+  - `create-plugin` -- creating plugins with `@Plugin`, providers, and context extensions
+  - `configure-auth` -- authentication and session configuration (not decorator-focused)

package/catalog/frontmcp-development/references/official-adapters.md

@@ -0,0 +1,194 @@
+# Official Adapters
+
+Adapters convert external definitions (OpenAPI specs, Lambda functions, etc.) into MCP tools, resources, and prompts automatically.
+
+## When to Use This Skill
+
+### Must Use
+
+- Converting an OpenAPI/Swagger specification into MCP tools automatically
+- Integrating a REST API that provides a public OpenAPI spec (Petstore, GitHub, Jira, Slack)
+- Setting up authentication (API key, bearer token, OAuth) for an adapter-generated API integration
+
+### Recommended
+
+- Registering multiple external APIs as namespaced tool sets in a single server
+- Enabling spec polling to auto-refresh tool definitions when the upstream API changes
+- Providing an inline OpenAPI spec for APIs without a hosted spec URL
+
+### Skip When
+
+- The external API has no OpenAPI spec and uses a custom protocol (see `create-adapter`)
+- You need cross-cutting behavior like caching or logging (see `create-plugin` or `official-plugins`)
+- You are building tools manually without an external spec (see `create-tool`)
+
+> **Decision:** Use this skill when you have an OpenAPI/Swagger spec and want to automatically generate MCP tools from it using `OpenApiAdapter`.
+
+## OpenAPI Adapter
+
+The primary official adapter. Converts OpenAPI/Swagger specifications into MCP tools — one tool per operation.
+
+### Installation
+
+```typescript
+import { OpenApiAdapter } from '@frontmcp/adapters';
+
+@App({
+  name: 'MyApp',
+  adapters: [
+    OpenApiAdapter.init({
+      name: 'petstore',
+      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+    }),
+  ],
+})
+class MyApp {}
+```
+
+Each OpenAPI operation becomes an MCP tool named `petstore:operationId`.
+
+### With Authentication
+
+```typescript
+// API Key via static auth
+OpenApiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  staticAuth: {
+    apiKey: process.env.API_KEY!,
+  },
+});
+
+// API Key via additional headers
+OpenApiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  additionalHeaders: {
+    'X-API-Key': process.env.API_KEY!,
+  },
+});
+
+// Bearer token via static auth
+OpenApiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  staticAuth: {
+    jwt: process.env.API_TOKEN!,
+  },
+});
+
+// Dynamic auth per tool using securityResolver
+OpenApiAdapter.init({
+  name: 'my-api',
+  url: 'https://api.example.com/openapi.json',
+  baseUrl: 'https://api.example.com',
+  securityResolver: (tool, ctx) => {
+    return { jwt: ctx.authInfo?.token };
+  },
+});
+```
+
+### Spec Polling
+
+Automatically refresh the OpenAPI spec at intervals:
+
+```typescript
+OpenApiAdapter.init({
+  name: 'evolving-api',
+  url: 'https://api.example.com/openapi.json',
+  polling: {
+    intervalMs: 300000, // Re-fetch every 5 minutes
+  },
+});
+```
+
+### Inline Spec
+
+Provide the OpenAPI spec directly instead of fetching from URL:
+
+```typescript
+OpenApiAdapter.init({
+  name: 'my-api',
+  spec: {
+    openapi: '3.0.0',
+    info: { title: 'My API', version: '1.0.0' },
+    paths: { ... },
+  },
+})
+```
+
+### Multiple Adapters
+
+Register adapters from different APIs in the same app:
+
+```typescript
+@App({
+  name: 'IntegrationHub',
+  adapters: [
+    OpenApiAdapter.init({ name: 'github', url: 'https://api.github.com/openapi.json' }),
+    OpenApiAdapter.init({ name: 'jira', url: 'https://jira.example.com/openapi.json' }),
+    OpenApiAdapter.init({ name: 'slack', url: 'https://slack.com/openapi.json' }),
+  ],
+})
+class IntegrationHub {}
+// Tools: github:createIssue, jira:createTicket, slack:postMessage, etc.
+```
+
+## Adapter vs Plugin
+
+| Aspect      | Adapter                              | Plugin                              |
+| ----------- | ------------------------------------ | ----------------------------------- |
+| Purpose     | Generate tools from external sources | Add cross-cutting behavior          |
+| Output      | Tools, resources, prompts            | Lifecycle hooks, context extensions |
+| Examples    | OpenAPI → MCP tools                  | Caching, auth, logging              |
+| When to use | Integrating APIs                     | Adding middleware                   |
+
+## Common Patterns
+
+| Pattern              | Correct                                                                      | Incorrect                                           | Why                                                                              |
+| -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Adapter registration | `OpenApiAdapter.init({ name: 'petstore', url: '...' })` in `adapters` array  | Placing adapter in `plugins` array                  | Adapters go in `adapters`, not `plugins`; they serve different purposes          |
+| Tool naming          | Tools auto-named as `petstore:operationId` using adapter `name` as namespace | Expecting flat names like `listPets`                | Adapter name is prepended to prevent collisions across multiple adapters         |
+| Auth configuration   | `staticAuth: { jwt: process.env.API_TOKEN! }` or `additionalHeaders`         | Hardcoding secrets: `staticAuth: { jwt: 'sk-xxx' }` | Always use environment variables for secrets; never commit tokens                |
+| Spec source          | Use `url` for hosted specs or `spec` for inline definitions                  | Using both `url` and `spec` simultaneously          | Only one source should be provided; `spec` takes precedence and `url` is ignored |
+| Multiple APIs        | Register separate `OpenApiAdapter.init()` calls with unique `name` values    | Using the same `name` for different adapters        | Duplicate names cause tool naming collisions                                     |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@frontmcp/adapters` package is installed
+- [ ] `OpenApiAdapter.init()` is in the `adapters` array of `@App`
+- [ ] Adapter has a unique `name` for tool namespacing
+- [ ] `url` points to a valid, reachable OpenAPI JSON/YAML endpoint (or `spec` is inline)
+
+### Runtime
+
+- [ ] Generated tools appear in `tools/list` with `<name>:<operationId>` naming
+- [ ] Auth headers are sent correctly on API calls
+- [ ] Spec polling refreshes tool definitions at the configured interval
+- [ ] Invalid spec URL produces a clear startup error
+
+### Production
+
+- [ ] API tokens and secrets are loaded from environment variables
+- [ ] Polling interval is appropriate for the API's update frequency
+- [ ] Multiple adapter registrations use distinct names
+
+## Troubleshooting
+
+| Problem                            | Cause                                                  | Solution                                                                                                                                                                        |
+| ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No tools generated from spec       | Spec URL returns non-OpenAPI content or is unreachable | Verify URL returns valid OpenAPI 3.x JSON; check network access                                                                                                                 |
+| Authentication errors on API calls | Wrong auth config or missing credentials               | Configure `staticAuth` for fixed credentials, `securityResolver`/`authProviderMapper` for dynamic auth, or `additionalHeaders` for header-based tokens; verify env vars are set |
+| Duplicate tool name error          | Two adapters registered with the same `name`           | Give each adapter a unique `name` (e.g., `'github'`, `'jira'`)                                                                                                                  |
+| Stale tools after API update       | Spec polling not configured                            | Add `polling: { intervalMs: 300000 }` to refresh every 5 minutes                                                                                                                |
+| TypeScript error importing adapter | Wrong import path                                      | Import from `@frontmcp/adapters`: `import { OpenApiAdapter } from '@frontmcp/adapters'`                                                                                         |
+
+## Reference
+
+- [Adapter Overview Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
+- Related skills: `create-adapter`, `create-plugin`, `create-tool`

package/catalog/{plugins/official-plugins/SKILL.md → frontmcp-development/references/official-plugins.md}

@@ -1,18 +1,29 @@
----
-name: official-plugins
-description: Install and configure official FrontMCP plugins including CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Use when adding caching, memory, tool approval, feature gating, or CodeCall orchestration.
-tags: [plugins, codecall, remember, approval, cache, feature-flags, dashboard]
-priority: 9
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/plugins/overview
----
-
 # Official FrontMCP Plugins
 
 FrontMCP ships 6 official plugins that extend server behavior with cross-cutting concerns: semantic tool discovery, session memory, authorization workflows, result caching, feature gating, and visual monitoring. Install individually or via `@frontmcp/plugins` (meta-package re-exporting cache, codecall, dashboard, and remember).
 
+## When to Use This Skill
+
+### Must Use
+
+- Installing and configuring any official FrontMCP plugin (CodeCall, Remember, Approval, Cache, Feature Flags, Dashboard)
+- Adding session memory, tool caching, or authorization workflows to an existing server
+- Integrating feature flag services (LaunchDarkly, Split.io, Unleash) to gate tools at runtime
+
+### Recommended
+
+- Setting up the Dashboard plugin for visual monitoring of server structure in development
+- Configuring CodeCall for semantic tool discovery when the server has many tools
+- Combining multiple official plugins in a production deployment
+
+### Skip When
+
+- You need to build a custom plugin with your own providers and context extensions (see `create-plugin`)
+- You only need lifecycle hooks without installing an official plugin (see `create-plugin-hooks`)
+- You need to generate tools from an OpenAPI spec (see `official-adapters`)
+
+> **Decision:** Use this skill when you need to install, configure, or customize one or more of the 6 official FrontMCP plugins.
+
 All plugins follow the `DynamicPlugin` pattern and are registered via `@FrontMcp({ plugins: [...] })`.
 
 ```typescript
@@ -24,7 +35,7 @@ import CachePlugin from '@frontmcp/plugin-cache';
 import FeatureFlagPlugin from '@frontmcp/plugin-feature-flags';
 import DashboardPlugin from '@frontmcp/plugin-dashboard';
 
-@App()
+@App({ name: 'MyApp' })
 class MyApp {}
 
 @FrontMcp({
@@ -430,7 +441,7 @@ A tool is cached if it matches any pattern OR has `cache: true` (or a cache obje
 
 Send the bypass header to skip caching for a specific request:
 
-```
+```text
 x-frontmcp-disable-cache: true
 ```
 
@@ -654,14 +665,49 @@ All official plugins use the static `init()` pattern inherited from `DynamicPlug
 class ProductionServer {}
 ```
 
+## Common Patterns
+
+| Pattern                  | Correct                                                                          | Incorrect                                                                       | Why                                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Plugin registration      | `plugins: [RememberPlugin.init({ type: 'memory' })]`                             | `plugins: [new RememberPlugin({ type: 'memory' })]`                             | Official plugins use `DynamicPlugin.init()` static method; direct instantiation bypasses provider wiring |
+| Remember storage in prod | `RememberPlugin.init({ type: 'redis', config: { host: '...' } })`                | `RememberPlugin.init({ type: 'memory' })` in production                         | Memory storage loses data on restart; use Redis or Vercel KV for persistence                             |
+| Cache TTL units          | `defaultTTL: 3600` (seconds)                                                     | `defaultTTL: 3600000` (milliseconds)                                            | Cache TTL is in seconds, not milliseconds; 3600000 = 41 days                                             |
+| Feature flag gating      | `@Tool({ featureFlag: 'my-flag' })` on the tool decorator                        | Checking `this.featureFlags.isEnabled()` inside `execute()` and returning early | Decorator-level gating hides the tool from `list_tools`; manual check still exposes it                   |
+| Dashboard in production  | `DashboardPlugin.init({ enabled: true, auth: { enabled: true, token: '...' } })` | `DashboardPlugin.init({})` without auth in production                           | Dashboard auto-disables in production; if enabled, always set auth token                                 |
+
+## Verification Checklist
+
+### Installation
+
+- [ ] Plugin package is installed (`@frontmcp/plugin-codecall`, `@frontmcp/plugin-remember`, etc.)
+- [ ] Plugin is registered via `.init()` in the `plugins` array of `@FrontMcp`
+- [ ] Required configuration options are provided (storage type, API keys, endpoints)
+
+### Runtime
+
+- [ ] `this.remember` / `this.approval` / `this.featureFlags` resolves in tool context
+- [ ] Cache plugin returns cached results on repeated identical calls
+- [ ] Feature-flagged tools are hidden from `list_tools` when flag is off
+- [ ] Dashboard is accessible at configured `basePath` (default: `/dashboard`)
+- [ ] Approval plugin blocks unapproved tools and grants approval correctly
+
+### Production
+
+- [ ] Redis or external storage is configured for Remember and Cache plugins
+- [ ] Dashboard authentication is enabled with a secret token
+- [ ] Feature flag adapter connects to external service (not `'static'`)
+
+## Troubleshooting
+
+| Problem                           | Cause                                                                            | Solution                                                                           |
+| --------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `this.remember` is undefined      | RememberPlugin not registered or missing `.init()`                               | Add `RememberPlugin.init({ type: 'memory' })` to `plugins` array                   |
+| Cache not working for a tool      | Tool name does not match any `toolPatterns` glob and `cache` metadata is not set | Add `cache: true` to `@Tool` decorator or add matching pattern to `toolPatterns`   |
+| Feature flag always returns false | Using `'static'` adapter with flag not in the `flags` map                        | Add the flag key to `flags: { 'my-flag': true }` or check adapter connection       |
+| Dashboard returns 404             | Plugin auto-disabled in production (`NODE_ENV=production`)                       | Set `enabled: true` explicitly in `DashboardPlugin.init()` options                 |
+| Approval webhook times out        | Callback URL not reachable from the external approval service                    | Verify `callbackPath` is publicly accessible and matches the webhook configuration |
+
 ## Reference
 
-- Plugins docs: [docs.agentfront.dev/frontmcp/plugins/overview](https://docs.agentfront.dev/frontmcp/plugins/overview)
-- `DynamicPlugin` base class: import from `@frontmcp/sdk`
-- CodeCall: `@frontmcp/plugin-codecall` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-codecall) | [docs](https://docs.agentfront.dev/frontmcp/plugins/codecall/overview)
-- Remember: `@frontmcp/plugin-remember` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-remember) | [docs](https://docs.agentfront.dev/frontmcp/plugins/remember-plugin)
-- Approval: `@frontmcp/plugin-approval` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-approval)
-- Cache: `@frontmcp/plugin-cache` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-cache) | [docs](https://docs.agentfront.dev/frontmcp/plugins/cache-plugin)
-- Feature Flags: `@frontmcp/plugin-feature-flags` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-feature-flags) | [docs](https://docs.agentfront.dev/frontmcp/plugins/feature-flags-plugin)
-- Dashboard: `@frontmcp/plugin-dashboard` — [source](https://github.com/agentfront/frontmcp/tree/main/plugins/plugin-dashboard)
-- Meta-package: `@frontmcp/plugins` (re-exports cache, codecall, dashboard, remember)
+- [Plugins Overview Documentation](https://docs.agentfront.dev/frontmcp/plugins/overview)
+- Related skills: `create-plugin`, `create-plugin-hooks`, `create-tool`