@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

@@ -1,29 +1,33 @@
 ---
 name: create-job
-description: Create long-running jobs with retry policies, progress tracking, and permission controls. Use when building background tasks, data processing pipelines, or scheduled operations.
-tags: [job, background, retry, progress, long-running]
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/jobs
+description: Create long-running background jobs with retry policies, progress tracking, and permissions
 ---
 
 # Creating Jobs
 
 Jobs are long-running background tasks with built-in retry policies, progress tracking, and permission controls. Unlike tools (which execute synchronously within a request), jobs run asynchronously and persist their state across retries and restarts.
 
-## When to Use @Job
+## When to Use This Skill
 
-Use `@Job` when you need to run work that may take longer than a request cycle, needs retry guarantees, or should track progress over time. Examples include:
+### Must Use
 
-- Data processing and ETL pipelines
-- File imports and exports
-- Report generation
-- Scheduled maintenance tasks
-- External API synchronization
+- Running work that takes longer than a request cycle (ETL pipelines, large imports)
+- Tasks that need automatic retry with exponential backoff on failure
+- Background operations that must track and report progress over time
 
-If the work completes in under a few seconds and does not need retry or progress tracking, use a `@Tool` instead.
+### Recommended
+
+- Scheduled maintenance tasks or periodic data synchronization
+- Operations requiring permission controls (role-based, scope-based access)
+- Work that must persist state across retries and server restarts
+
+### Skip When
+
+- The work completes in a few seconds and needs no retry or progress tracking (see `create-tool`)
+- You need to expose read-only data at a URI (see `create-resource`)
+- The task requires autonomous LLM reasoning rather than a deterministic pipeline (see `create-agent`)
+
+> **Decision:** Use this skill when you need a long-running background task with retry policies, progress tracking, or permission controls.
 
 ## Class-Based Pattern
 
@@ -564,3 +568,46 @@ class DataApp {}
 })
 class DataServer {}
 ```
+
+## Common Patterns
+
+| Pattern           | Correct                                                            | Incorrect                                        | Why                                                                            |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| Progress tracking | `this.progress(50, 100, 'Processing batch 5')`                     | Not reporting progress                           | Progress is persisted and queryable; essential for long-running visibility     |
+| Retry config      | `retry: { maxAttempts: 3, backoffMs: 2000, backoffMultiplier: 2 }` | Implementing retry logic manually in `execute()` | Framework handles retry with exponential backoff and attempt tracking          |
+| Attempt awareness | Check `this.attempt` for retry-specific logic                      | Ignoring attempt number                          | `this.attempt` is 1-based; use it to log retry context or adjust behavior      |
+| Job logging       | `this.log('message')` for persistent, queryable logs               | Using `console.log()`                            | `this.log()` persists with job state; `console.log` is ephemeral               |
+| Permissions       | Use `permissions: { roles: [...], scopes: [...] }` declaratively   | Checking roles manually inside `execute()`       | Declarative permissions are enforced before execution and are self-documenting |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Job class extends `JobContext` and implements `execute(input)`
+- [ ] `@Job` decorator has `name`, `inputSchema`, and `outputSchema`
+- [ ] `retry` policy is configured if the job may fail transiently
+- [ ] `timeout` is set appropriately for the expected execution duration
+- [ ] Job is registered in `jobs` array of `@App`
+
+### Runtime
+
+- [ ] `jobs.enabled: true` is set in `@FrontMcp` configuration with a store
+- [ ] Job executes and returns output matching `outputSchema`
+- [ ] Progress is reported and queryable during execution
+- [ ] Retry fires with correct backoff delays on transient failures
+- [ ] Permissions block unauthorized users before execution starts
+
+## 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` |
+
+## Reference
+
+- [Jobs Documentation](https://docs.agentfront.dev/frontmcp/servers/jobs)
+- Related skills: `create-tool`, `create-provider`, `create-agent`, `create-workflow`

package/catalog/{plugins/create-plugin-hooks/SKILL.md → frontmcp-development/references/create-plugin-hooks.md}

@@ -1,18 +1,34 @@
 ---
 name: create-plugin-hooks
-description: Create plugins with flow lifecycle hooks using @Will, @Did, @Stage, and @Around decorators. Use when intercepting tool calls, adding logging, modifying request/response, or implementing cross-cutting middleware.
-tags: [plugin, hooks, will, did, stage, around, flow, middleware]
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/plugins/creating-plugins
+description: Intercept and extend FrontMCP flows using before, after, around, and stage hook decorators
 ---
 
 # Creating Plugins with Flow Lifecycle Hooks
 
 Plugins intercept and extend FrontMCP flows using lifecycle hook decorators. Every flow (tool calls, resource reads, prompt gets, etc.) is composed of **stages**, and hooks let you run logic before, after, around, or instead of any stage.
 
+## When to Use This Skill
+
+### Must Use
+
+- Adding before/after logic to tool execution (logging, metrics, input enrichment)
+- Implementing authorization checks that intercept flows before they reach the tool
+- Wrapping stage execution with caching, retry, or timing logic via `@Around`
+
+### Recommended
+
+- Replacing a built-in stage entirely with custom logic using `@Stage`
+- Adding hooks directly on a `@Tool` class for tool-specific pre/post processing
+- Filtering hook execution by tool name or context properties using `filter` predicates
+
+### Skip When
+
+- You need providers, context extensions, or contributed tools (see `create-plugin`)
+- You want to use an existing official plugin that already provides hooks (see `official-plugins`)
+- You are building a simple tool with no cross-cutting concerns (see `create-tool`)
+
+> **Decision:** Use this skill when you need to intercept or wrap flow stages with `@Will`, `@Did`, `@Around`, or `@Stage` decorators.
+
 ## Hook Decorator Types
 
 FrontMCP provides four hook decorators obtained via `FlowHooksOf(flowName)`:
@@ -47,6 +63,42 @@ const { Stage, Will, Did, Around } = FlowHooksOf('tools:call-tool');
 | `http:request`             | HTTP request handling    |
 | `agents:call-agent`        | Agent invocation         |
 
+## Server Lifecycle Hooks
+
+In addition to flow-based hooks, plugins can register callbacks for server lifecycle events. These are not decorator-based — they use the `scope.onServerStarted()` API.
+
+### `onServerStarted()`
+
+Runs after the HTTP server is fully initialized and listening. Use for warming caches, starting background indexing, or logging readiness.
+
+```typescript
+import { Plugin, DynamicPlugin } from '@frontmcp/sdk';
+
+@Plugin({
+  name: 'cache-warmer',
+  description: 'Warms caches when the server starts',
+  providers: [CacheService],
+})
+class CacheWarmerPlugin extends DynamicPlugin<{}> {
+  constructor(scope: ScopeEntry) {
+    super();
+    // Register lifecycle callback
+    scope.onServerStarted(async () => {
+      const cache = this.get(CacheService);
+      await cache.warmAll();
+      console.log('Cache warmed successfully');
+    });
+  }
+}
+```
+
+**Signature:** `scope.onServerStarted(callback: () => void | Promise<void>): void`
+
+- Callbacks are stored and executed after `server.start()` completes
+- Supports both sync and async callbacks
+- Multiple callbacks are executed in registration order with `await`
+- Typically used in plugin constructors or provider `onInit()` methods
+
 ## Pre-Built Hook Type Exports
 
 For convenience, FrontMCP exports typed aliases so you do not need to call `FlowHooksOf` directly:
@@ -280,3 +332,44 @@ parseInput → findTool → checkToolAuthorization → createToolCallContext
 ```
 
 Any stage can have `@Will`, `@Did`, `@Stage`, or `@Around` hooks.
+
+## Common Patterns
+
+| Pattern               | Correct                                                               | Incorrect                                                              | Why                                                                                |
+| --------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Hook decorator source | `const { Will, Did } = ToolHook;` or `FlowHooksOf('tools:call-tool')` | Importing `Will` directly from `@frontmcp/sdk`                         | Decorators must be bound to a specific flow via `FlowHooksOf` or pre-built exports |
+| Hook priority         | `@Will('execute', { priority: 100 })` for early hooks                 | Relying on array order without priority                                | Multiple hooks on the same stage need explicit priority; higher runs first         |
+| Around next()         | `const result = await next(); return result;`                         | Forgetting to call `next()` in `@Around`                               | Omitting `next()` silently skips the wrapped stage and all downstream hooks        |
+| Filter predicate      | `filter: (ctx) => ctx.toolName !== 'health_check'`                    | Checking tool name inside the hook body and returning early            | Filters skip the hook cleanly; returning early may leave state inconsistent        |
+| Tool-level hooks      | `@Will('execute')` on a `@Tool` class (scoped to that tool)           | `@Will('execute')` on a `@Plugin` class expecting tool-scoped behavior | Plugin hooks fire for all tools; tool-level hooks fire only for that tool          |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Hook decorator is obtained from `FlowHooksOf(flowName)` or a pre-built export (e.g., `ToolHook`)
+- [ ] Stage name matches an actual stage in the targeted flow (e.g., `execute`, `validateInput`)
+- [ ] Plugin with hooks is registered in `plugins` array of `@App` or `@FrontMcp`
+
+### Runtime
+
+- [ ] `@Will` hook fires before the targeted stage
+- [ ] `@Did` hook fires after the targeted stage completes
+- [ ] `@Around` hook calls `next()` and the wrapped stage executes
+- [ ] `@Stage` replacement returns a valid response for the flow
+- [ ] Hook `filter` correctly skips invocations for excluded tools
+
+## Troubleshooting
+
+| Problem                                       | Cause                                            | Solution                                                                          |
+| --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
+| Hook never fires                              | Plugin not registered in `plugins` array         | Add plugin class to `@App` or `@FrontMcp` `plugins` array                         |
+| Hook fires for wrong flow                     | Used wrong flow name in `FlowHooksOf`            | Verify flow name matches (e.g., `'tools:call-tool'` not `'tool:call'`)            |
+| `@Around` skips the stage entirely            | `next()` not called inside the around handler    | Always `await next()` to execute the wrapped stage                                |
+| Multiple hooks execute in wrong order         | Priorities not set or conflicting                | Set explicit `priority` values; higher numbers execute first                      |
+| `@Stage` replacement causes downstream errors | Return value shape does not match stage contract | Ensure the return matches what the next stage expects (e.g., MCP response format) |
+
+## Reference
+
+- [Plugin Hooks Documentation](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)
+- Related skills: `create-plugin`, `official-plugins`, `create-tool`