@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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

@@ -0,0 +1,165 @@
+# Creating Custom Adapters
+
+Build adapters that automatically generate MCP tools, resources, and prompts from external sources — databases, GraphQL schemas, proprietary APIs, or any definition format.
+
+## When to Use This Skill
+
+### Must Use
+
+- Integrating a non-OpenAPI source (GraphQL, gRPC, database schema) that should generate MCP tools automatically
+- Building a reusable adapter that converts external definitions into tools, resources, or prompts at startup
+- Creating tools dynamically at runtime based on external state or configuration
+
+### Recommended
+
+- Wrapping a proprietary internal API that has its own schema format
+- Auto-generating tools from a database schema or config file on server start
+- Building an adapter that polls an external source and refreshes tool definitions periodically
+
+### Skip When
+
+- The external API has an OpenAPI/Swagger spec (see `official-adapters`)
+- You need cross-cutting middleware behavior like logging or caching (see `create-plugin`)
+- You are building a single static tool manually (see `create-tool`)
+
+> **Decision:** Use this skill when you need to auto-generate MCP tools, resources, or prompts from a non-OpenAPI external source by extending `DynamicAdapter`.
+
+## Step 1: Extend DynamicAdapter
+
+```typescript
+import { DynamicAdapter, type FrontMcpAdapterResponse } from '@frontmcp/sdk';
+
+interface MyAdapterOptions {
+  endpoint: string;
+  apiKey: string;
+}
+
+class MyApiAdapter extends DynamicAdapter<MyAdapterOptions> {
+  declare __options_brand: MyAdapterOptions;
+
+  async fetch(): Promise<FrontMcpAdapterResponse> {
+    // Fetch definitions from external source
+    const res = await globalThis.fetch(this.options.endpoint, {
+      headers: { Authorization: `Bearer ${this.options.apiKey}` },
+    });
+    const schema = await res.json();
+
+    // Convert to MCP tool definitions
+    return {
+      tools: schema.operations.map((op: { name: string; description: string; params: Record<string, unknown> }) => ({
+        name: op.name,
+        description: op.description,
+        inputSchema: this.convertParams(op.params),
+        execute: async (input: Record<string, unknown>) => {
+          return this.callApi(op.name, input);
+        },
+      })),
+      resources: [],
+      prompts: [],
+    };
+  }
+
+  private convertParams(params: Record<string, unknown>) {
+    // Convert external param definitions to Zod schemas
+    // ...
+  }
+
+  private async callApi(operation: string, input: Record<string, unknown>) {
+    // Call the external API
+    // ...
+  }
+}
+```
+
+## Step 2: Register
+
+```typescript
+@App({
+  name: 'MyApp',
+  adapters: [
+    MyApiAdapter.init({
+      name: 'my-api',
+      endpoint: 'https://api.example.com/schema',
+      apiKey: process.env.API_KEY!,
+    }),
+  ],
+})
+class MyApp {}
+```
+
+## FrontMcpAdapterResponse
+
+The `fetch()` method returns tools, resources, and prompts to register:
+
+```typescript
+interface FrontMcpAdapterResponse {
+  tools?: AdapterToolDefinition[];
+  resources?: AdapterResourceDefinition[];
+  prompts?: AdapterPromptDefinition[];
+}
+```
+
+## Static init()
+
+`DynamicAdapter` provides a static `init()` method inherited by all subclasses:
+
+```typescript
+// Usage — no manual instantiation needed
+const adapter = MyApiAdapter.init({
+  name: 'my-api',        // Required: adapter name (used for tool namespacing)
+  endpoint: '...',
+  apiKey: '...',
+});
+
+// Register in @App
+@App({ adapters: [adapter] })
+```
+
+## Nx Generator
+
+```bash
+nx generate @frontmcp/nx:adapter my-adapter --project=my-app
+```
+
+Creates a `DynamicAdapter` subclass in `src/adapters/my-adapter.adapter.ts`.
+
+## Common Patterns
+
+| Pattern                 | Correct                                                       | Incorrect                                              | Why                                                                             |
+| ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Adapter registration    | `MyAdapter.init({ name: 'my-api', ... })` in `adapters` array | `new MyAdapter({ ... })` directly                      | `init()` returns the proper provider entry for DI wiring                        |
+| Options branding        | `declare __options_brand: MyAdapterOptions;` in adapter class | Omitting the brand declaration                         | Brand ensures TypeScript infers the correct options type for `init()`           |
+| Fetch return type       | Return `{ tools: [...], resources: [...], prompts: [...] }`   | Returning raw API response without conversion          | `fetch()` must return `FrontMcpAdapterResponse` with MCP-compatible definitions |
+| Tool naming             | Namespace tools: `name: 'my-api:operation-name'`              | Flat names without namespace: `name: 'operation-name'` | Namespacing prevents collisions when multiple adapters are registered           |
+| Error handling in fetch | Throw descriptive errors with endpoint info                   | Silently returning empty arrays on failure             | Adapter errors should surface at startup so misconfigurations are caught early  |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Adapter class extends `DynamicAdapter<TOptions>`
+- [ ] `__options_brand` is declared with the correct options type
+- [ ] `fetch()` method is implemented and returns `FrontMcpAdapterResponse`
+- [ ] Adapter is registered via `.init()` in the `adapters` array of `@App`
+
+### Runtime
+
+- [ ] Generated tools appear in `tools/list` MCP response
+- [ ] Tool names are namespaced with the adapter name (e.g., `my-api:operationId`)
+- [ ] Generated tools accept valid input and return expected output
+- [ ] Adapter fetch errors produce clear startup error messages
+
+## Troubleshooting
+
+| Problem                                    | Cause                                                       | Solution                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| No tools appear after adapter registration | `fetch()` returns empty `tools` array                       | Verify external source is reachable and response is parsed correctly             |
+| TypeScript error on `.init()` options      | Missing `__options_brand` declaration                       | Add `declare __options_brand: MyAdapterOptions;` to the adapter class            |
+| Tool input validation fails                | `inputSchema` conversion does not produce valid Zod schemas | Verify `convertParams` produces `z.object()` shapes matching the external schema |
+| Duplicate tool name error                  | Multiple adapters produce tools with the same name          | Use unique `name` parameter in `init()` to namespace tools                       |
+| Adapter not found at runtime               | Registered in wrong `@App` or not in `adapters` array       | Ensure `.init()` result is in the `adapters` array of the correct `@App`         |
+
+## Reference
+
+- [Adapter Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
+- Related skills: `official-adapters`, `create-plugin`, `create-tool`

package/catalog/{development/create-agent/references/llm-config.md → frontmcp-development/references/create-agent-llm-config.md}

@@ -1,13 +1,13 @@
 # Agent LLM Configuration Reference
 
-## Supported Adapters
+## Supported Providers
 
 ### Anthropic
 
 ```typescript
 llm: {
-  adapter: 'anthropic',
-  model: 'claude-sonnet-4-20250514',
+  provider: 'anthropic', // Any supported provider — 'anthropic', 'openai', etc.
+  model: 'claude-sonnet-4-20250514', // Any supported model for the chosen provider
   apiKey: { env: 'ANTHROPIC_API_KEY' },
   maxTokens: 4096,
 }
@@ -17,8 +17,8 @@ llm: {
 
 ```typescript
 llm: {
-  adapter: 'openai',
-  model: 'gpt-4o',
+  provider: 'openai',
+  model: 'gpt-4o', // Any supported model for the chosen provider
   apiKey: { env: 'OPENAI_API_KEY' },
   maxTokens: 4096,
 }

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

@@ -1,35 +1,30 @@
----
-name: create-agent
-description: Create autonomous AI agents with inner tools, LLM providers, and multi-agent swarms. Use when building agents, configuring LLM adapters, adding inner tools, or setting up agent handoff.
-tags: [agent, ai, llm, tools, autonomous]
-parameters:
-  - name: llm-provider
-    description: LLM provider to use
-    type: string
-    default: anthropic
-  - name: name
-    description: Agent name
-    type: string
-    required: true
-examples:
-  - scenario: Create a code review agent with GitHub tools
-    expected-outcome: Agent autonomously reviews PRs using inner tools
-  - scenario: Create a multi-agent swarm for complex workflows
-    expected-outcome: Agents hand off tasks to each other
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/agents
----
-
 # Creating an Autonomous Agent
 
 Agents are autonomous AI entities that use an LLM to reason, plan, and invoke inner tools to accomplish goals. In FrontMCP, agents are TypeScript classes that extend `AgentContext`, decorated with `@Agent`, and registered on a `@FrontMcp` server or inside an `@App`.
 
-## When to Use @Agent vs @Tool
+## When to Use This Skill
+
+### Must Use
+
+- Building an autonomous AI entity that uses LLM reasoning to decide which tools to call
+- Orchestrating multi-step workflows where the agent plans, acts, and iterates toward a goal
+- Creating multi-agent swarms with handoff between specialized agents
+
+### Recommended
+
+- Performing complex tasks that require chaining multiple inner tools with LLM-driven decisions
+- Implementing structured multi-pass review (security pass, quality pass, synthesis)
+- Composing nested sub-agents with different LLM configs for specialized subtasks
 
-Use `@Agent` when the task requires autonomous reasoning, multi-step planning, or LLM-driven decision making. An agent receives a goal, decides which tools to call, interprets results, and iterates until the goal is met. Use `@Tool` when you need a direct, deterministic function that executes a single action without LLM involvement.
+### Skip When
+
+- You need a direct, deterministic function that executes a single action (see `create-tool`)
+- You are building a reusable conversation template without autonomous execution (see `create-prompt`)
+- You only need to expose readable data at a URI (see `create-resource`)
+
+> **Decision:** Use this skill when the task requires autonomous LLM-driven reasoning, tool invocation, and iterative planning -- not a single deterministic action.
+
+### @Agent vs @Tool Quick Comparison
 
 | Aspect          | @Agent                          | @Tool                        |
 | --------------- | ------------------------------- | ---------------------------- |
@@ -50,8 +45,8 @@ import { z } from 'zod';
   name: 'code_reviewer',
   description: 'Reviews code changes and provides feedback',
   llm: {
-    adapter: 'anthropic',
-    model: 'claude-sonnet-4-20250514',
+    provider: 'anthropic', // Any supported provider — 'anthropic', 'openai', etc.
+    model: 'claude-sonnet-4-20250514', // Any supported model for the chosen provider
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
   inputSchema: {
@@ -110,7 +105,7 @@ The `llm` field is required and configures which LLM provider and model the agen
   name: 'my_agent',
   description: 'An agent with LLM config',
   llm: {
-    adapter: 'anthropic',          // 'anthropic' or 'openai'
+    provider: 'anthropic',          // 'anthropic' or 'openai'
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' }, // read from env var
   },
@@ -122,7 +117,7 @@ The `apiKey` field accepts either an object `{ env: 'ENV_VAR_NAME' }` to read fr
 ```typescript
 // OpenAI example
 llm: {
-  adapter: 'openai',
+  provider: 'openai',
   model: 'gpt-4o',
   apiKey: { env: 'OPENAI_API_KEY' },
 },
@@ -139,7 +134,7 @@ Override `execute()` when you need custom orchestration logic:
   name: 'structured_reviewer',
   description: 'Reviews code with a structured multi-pass approach',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -193,7 +188,7 @@ Use `completion()` for a single LLM call that returns the full response, and `st
   name: 'summarizer',
   description: 'Summarizes text using LLM',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -287,7 +282,7 @@ class PostReviewCommentTool extends ToolContext {
   name: 'pr_reviewer',
   description: 'Autonomously reviews GitHub pull requests',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -315,7 +310,7 @@ Use `exports: { tools: [] }` to expose specific tools that the agent makes avail
   name: 'data_pipeline',
   description: 'Data processing pipeline agent',
   llm: {
-    adapter: 'openai',
+    provider: 'openai',
     model: 'gpt-4o',
     apiKey: { env: 'OPENAI_API_KEY' },
   },
@@ -333,7 +328,7 @@ Use the `agents` array to compose agents from smaller, specialized sub-agents. E
 @Agent({
   name: 'security_auditor',
   description: 'Audits code for security vulnerabilities',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   systemInstructions: 'Focus on OWASP Top 10 vulnerabilities.',
   tools: [StaticAnalysisTool],
 })
@@ -342,7 +337,7 @@ class SecurityAuditorAgent extends AgentContext {}
 @Agent({
   name: 'performance_auditor',
   description: 'Audits code for performance issues',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   systemInstructions: 'Focus on time complexity, memory leaks, and N+1 queries.',
   tools: [ProfilerTool],
 })
@@ -351,7 +346,7 @@ class PerformanceAuditorAgent extends AgentContext {}
 @Agent({
   name: 'code_auditor',
   description: 'Comprehensive code auditor that delegates to specialized sub-agents',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   inputSchema: {
     repository: z.string().describe('Repository URL'),
     branch: z.string().default('main').describe('Branch to audit'),
@@ -372,7 +367,7 @@ Swarm mode enables multi-agent handoff, where agents can transfer control to eac
 @Agent({
   name: 'triage_agent',
   description: 'Triages incoming requests and hands off to specialists',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   inputSchema: {
     request: z.string().describe('The incoming user request'),
   },
@@ -391,7 +386,7 @@ class TriageAgent extends AgentContext {}
 @Agent({
   name: 'billing_agent',
   description: 'Handles billing and payment inquiries',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   tools: [LookupInvoiceTool, ProcessRefundTool],
   swarm: {
     role: 'specialist',
@@ -413,7 +408,7 @@ const QuickSummarizer = agent({
   name: 'quick_summarizer',
   description: 'Summarizes text quickly',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -494,7 +489,7 @@ Protect agents with throttling controls:
   name: 'expensive_agent',
   description: 'An agent that performs expensive LLM operations',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -523,7 +518,7 @@ Agents can include their own providers and plugins for self-contained dependency
   name: 'database_agent',
   description: 'Agent that interacts with databases',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -548,7 +543,7 @@ Agents can include resources and prompts that are available within the agent's s
   name: 'docs_agent',
   description: 'Agent that manages documentation',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -561,3 +556,46 @@ Agents can include resources and prompts that are available within the agent's s
 })
 class DocsAgent extends AgentContext {}
 ```
+
+## Common Patterns
+
+| Pattern                 | Correct                                                                       | Incorrect                                                      | Why                                                                             |
+| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| LLM config              | `llm: { provider: 'anthropic', model: '...', apiKey: { env: 'KEY' } }`        | `llm: { provider: 'anthropic', apiKey: 'sk-hardcoded' }`       | Environment variable references prevent leaking secrets in code                 |
+| Inner tools vs exported | `tools: [...]` for agent-private; `exports: { tools: [...] }` for MCP-visible | Putting all tools in `tools` and expecting clients to see them | Inner tools are private to the agent; only exported tools appear in MCP listing |
+| Custom execute          | Override `execute()` for multi-pass orchestration                             | Putting all logic in system instructions                       | Custom `execute()` gives structured control over completion calls and stages    |
+| Sub-agents              | Use `agents: [SubAgent]` for composition                                      | Calling another agent's `execute()` directly                   | The `agents` array enables proper lifecycle, scope isolation, and handoff       |
+| Swarm handoff           | Use `swarm.handoff` with `agent` name and `condition`                         | Manually routing between agents in `execute()`                 | Swarm config enables declarative, LLM-driven handoff between agents             |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Agent class extends `AgentContext` and has `@Agent` decorator with `name`, `description`, and `llm`
+- [ ] `inputSchema` is defined with Zod raw shape for input validation
+- [ ] Inner tools in `tools` array are valid `@Tool` classes
+- [ ] Agent is registered in `agents` array of `@App` or `@FrontMcp`
+- [ ] API key uses `{ env: 'VAR_NAME' }` pattern, not hardcoded strings
+
+### Runtime
+
+- [ ] Agent appears in MCP tool listing (agents surface as callable tools)
+- [ ] LLM adapter connects successfully to the configured provider
+- [ ] Inner tools are invoked correctly during the agent loop
+- [ ] `this.completion()` and `this.streamCompletion()` return valid responses
+- [ ] Swarm handoff transfers control to the correct specialist agent
+
+## Troubleshooting
+
+| Problem                             | Cause                                                 | Solution                                                                          |
+| ----------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Agent not appearing in tool listing | Not registered in `agents` array                      | Add agent class to `@App` or `@FrontMcp` `agents` array                           |
+| LLM authentication error            | API key not set or incorrect env variable             | Verify the environment variable name in `apiKey: { env: '...' }` is set           |
+| Inner tools not being called        | Tools not listed in `tools` array of `@Agent`         | Add tool classes to the `tools` field in the `@Agent` decorator                   |
+| Agent times out                     | No timeout or rate limit configured                   | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options         |
+| Swarm handoff fails                 | Target agent name does not match any registered agent | Ensure `handoff.agent` matches the `name` of a registered agent in the same scope |
+
+## Reference
+
+- [Agents Documentation](https://docs.agentfront.dev/frontmcp/servers/agents)
+- Related skills: `create-tool`, `create-provider`, `create-prompt`, `create-resource`

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

@@ -1,29 +1,28 @@
----
-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
----
-
 # 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
+
+### Must Use
+
+- 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
+
+### Recommended
 
-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:
+- 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
 
-- Data processing and ETL pipelines
-- File imports and exports
-- Report generation
-- Scheduled maintenance tasks
-- External API synchronization
+### Skip When
 
-If the work completes in under a few seconds and does not need retry or progress tracking, use a `@Tool` instead.
+- 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 +563,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,29 @@
----
-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
----
-
 # 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)`:
@@ -280,3 +291,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`