@frontmcp/skills 0.0.1 → 1.0.0-beta.9

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`

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

@@ -1,54 +1,29 @@
----
-name: create-plugin
-description: Build a FrontMCP plugin with lifecycle hooks and context extensions. Use when creating custom plugins, extending tool context, or adding cross-cutting concerns.
-tags:
-  - plugins
-  - extensibility
-  - hooks
-  - context
-bundle:
-  - full
-visibility: both
-priority: 5
-parameters:
-  - name: plugin-name
-    description: Name for the new plugin (kebab-case)
-    type: string
-    required: true
-  - name: with-context-extension
-    description: Whether the plugin adds properties to ExecutionContextBase
-    type: boolean
-    required: false
-    default: false
-  - name: with-dynamic-options
-    description: Whether the plugin accepts runtime configuration options
-    type: boolean
-    required: false
-    default: false
-examples:
-  - scenario: Create a simple logging plugin with no context extensions
-    parameters:
-      plugin-name: audit-log
-      with-context-extension: false
-    expected-outcome: A plugin that hooks into tool execution to log audit events
-  - scenario: Create an advanced plugin that extends ToolContext with a new property
-    parameters:
-      plugin-name: feature-flags
-      with-context-extension: true
-      with-dynamic-options: true
-    expected-outcome: A configurable plugin that adds this.featureFlags to all tool contexts
-license: MIT
-compatibility: Requires Node.js 18+ and @frontmcp/sdk
-metadata:
-  category: plugins
-  difficulty: advanced
-  docs: https://docs.agentfront.dev/frontmcp/plugins/creating-plugins
----
-
 # Create a FrontMCP Plugin
 
 This skill covers building custom plugins for FrontMCP and using all 6 official plugins. Plugins are modular units that extend server behavior through providers, context extensions, lifecycle hooks, and contributed tools/resources/prompts.
 
+## When to Use This Skill
+
+### Must Use
+
+- Adding cross-cutting behavior (logging, caching, auth) that applies across multiple tools
+- Extending `ExecutionContextBase` with new properties accessible via `this.propertyName` in tools
+- Contributing injectable providers that tools or other plugins depend on
+
+### Recommended
+
+- Building a configurable module with runtime options using the `DynamicPlugin` pattern
+- Extending the `@Tool` decorator metadata with custom fields (e.g., audit, approval)
+- Composing multiple related providers, hooks, and tools into a single installable unit
+
+### Skip When
+
+- You only need lifecycle hooks without providers or context extensions (see `create-plugin-hooks`)
+- You want to use an existing official plugin (see `official-plugins`)
+- You need to generate tools from an external API spec (see `create-adapter`)
+
+> **Decision:** Use this skill when you need a reusable module that bundles providers, context extensions, or contributed entries and registers them via `@Plugin`.
+
 ## Plugin Decorator Signature
 
 ```typescript
@@ -118,7 +93,7 @@ Register it in your server:
 import { FrontMcp, App } from '@frontmcp/sdk';
 import AuditLogPlugin from './plugins/audit-log.plugin';
 
-@App()
+@App({ name: 'MyApp' })
 class MyApp {}
 
 @FrontMcp({
@@ -318,19 +293,49 @@ class DeleteUserTool extends ToolContext {
 
 For official plugin installation, configuration, and examples, see the **official-plugins** skill. FrontMCP provides 6 official plugins: CodeCall, Remember, Approval, Cache, Feature Flags, and Dashboard. Install individually or via `@frontmcp/plugins` (meta-package).
 
-## Common Mistakes
+## Common Patterns
+
+| Pattern                        | Correct                                                                                        | Incorrect                                                             | Why                                                                          |
+| ------------------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Context extension registration | `contextExtensions: [{ property: 'auditLog', token: AuditLoggerToken }]` in metadata           | `Object.defineProperty(ExecutionContextBase.prototype, ...)` manually | SDK handles runtime installation; manual modification causes ordering issues |
+| Type augmentation              | `declare module '@frontmcp/sdk' { interface ExecutionContextBase { ... } }` in a separate file | Skipping the augmentation and casting `this` in tools                 | Without augmentation, TypeScript cannot type-check `this.auditLog`           |
+| Provider types                 | `Token<AuditLogger> = Symbol('AuditLogger')` with typed token                                  | `provide: Symbol('AuditLogger')` without type annotation              | Typed tokens enable compile-time DI resolution checking                      |
+| Plugin scope                   | `scope: 'app'` (default) for app-scoped behavior                                               | `scope: 'server'` when hooks should only apply to one app             | Server scope fires hooks for all apps in a gateway; default to app           |
+| Dynamic options                | Extend `DynamicPlugin<TOptions, TInput>` with `static dynamicProviders()`                      | Constructing providers in the constructor body                        | `dynamicProviders` runs before instantiation, enabling proper DI wiring      |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@Plugin` decorator has `name` and `description`
+- [ ] Providers are listed in `providers` array with typed tokens
+- [ ] Exported providers are listed in `exports` array
+- [ ] Context extensions have `property`, `token`, and `errorMessage` fields
+
+### Type Safety
+
+- [ ] Module augmentation file exists with `declare module '@frontmcp/sdk'` block
+- [ ] Augmented properties are `readonly` on `ExecutionContextBase`
+- [ ] Augmentation file is imported (side-effect import) in the plugin module
+
+### Runtime
+
+- [ ] Plugin is registered in `plugins` array of `@FrontMcp` or `@App`
+- [ ] `this.propertyName` resolves correctly in tool contexts
+- [ ] Missing plugin produces a clear error message (from `errorMessage`)
+- [ ] Dynamic plugin options are validated in `dynamicProviders()`
+
+## Troubleshooting
 
-- **Module-level side effects for context extension** -- do not call `installExtension()` at the top level of a module. This causes circular dependencies. The SDK handles installation via `contextExtensions` metadata.
-- **Forgetting the type augmentation** -- without `declare module '@frontmcp/sdk'`, TypeScript will not recognize `this.auditLog` in tools.
-- **Using `any` types in providers** -- use `unknown` for generic defaults.
-- **Scope confusion** -- `scope: 'server'` makes hooks fire for all apps in a gateway. Default to `scope: 'app'`.
-- **Direct prototype modification** -- use the `contextExtensions` metadata array instead of directly modifying `ExecutionContextBase.prototype`.
+| Problem                                           | Cause                                            | Solution                                                                        |
+| ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `this.auditLog` has type `any` or is unrecognized | Module augmentation file not imported            | Add side-effect import: `import './audit-log.context-extension'` in plugin file |
+| Circular dependency error at startup              | Calling `installExtension()` at module top level | Remove manual installation; use `contextExtensions` metadata array instead      |
+| Provider not found in tool context                | Provider not listed in plugin `exports`          | Add the provider to both `providers` and `exports` arrays                       |
+| Hooks fire for unrelated apps in gateway          | Plugin `scope` set to `'server'`                 | Change to `scope: 'app'` (default) unless server-wide behavior is intended      |
+| `DynamicPlugin.init()` options ignored            | Overriding constructor without calling `super()` | Ensure constructor calls `super()` and merges defaults properly                 |
 
 ## Reference
 
-- Plugin system docs: [docs.agentfront.dev/frontmcp/plugins/creating-plugins](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)
-- `@Plugin` decorator: import from `@frontmcp/sdk` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/sdk/src/common/decorators/plugin.decorator.ts)
-- `DynamicPlugin` base class: import from `@frontmcp/sdk` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/sdk/src/common/dynamic/dynamic.plugin.ts)
-- `PluginMetadata` interface (contextExtensions): import from `@frontmcp/sdk` — [source](https://github.com/agentfront/frontmcp/tree/main/libs/sdk/src/common/metadata/plugin.metadata.ts)
-- Official plugins: `@frontmcp/plugin-cache`, `@frontmcp/plugin-codecall`, `@frontmcp/plugin-remember`, `@frontmcp/plugin-approval`, `@frontmcp/plugin-feature-flags`, `@frontmcp/plugin-dashboard`
-- Meta-package: `@frontmcp/plugins` (re-exports cache, codecall, dashboard, remember)
+- [Plugin System Documentation](https://docs.agentfront.dev/frontmcp/plugins/creating-plugins)
+- Related skills: `create-plugin-hooks`, `official-plugins`, `create-adapter`, `create-provider`