@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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`

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

@@ -1,34 +1,28 @@
----
-name: create-prompt
-description: Create MCP prompts for reusable AI interaction patterns. Use when building prompts, defining prompt arguments, or creating conversation templates.
-tags: [prompts, mcp, templates, messages, decorator]
-tools:
-  - name: create_prompt
-    purpose: Scaffold a new prompt class
-parameters:
-  - name: name
-    description: Prompt name in kebab-case
-    type: string
-    required: true
-examples:
-  - scenario: Create a code review prompt with language argument
-    expected-outcome: Prompt registered and callable via MCP
-  - scenario: Create a multi-turn debugging prompt with assistant priming
-    expected-outcome: Prompt producing structured message sequences
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/prompts
----
-
 # Creating MCP Prompts
 
 Prompts define reusable AI interaction patterns in the MCP protocol. They produce structured message sequences that clients use to guide LLM conversations. In FrontMCP, prompts are classes extending `PromptContext`, decorated with `@Prompt`, that return `GetPromptResult` objects.
 
-## When to Use @Prompt
+## When to Use This Skill
+
+### Must Use
+
+- Building a reusable conversation template that AI clients invoke with arguments
+- Defining structured multi-turn message sequences (user/assistant patterns)
+- Creating domain-specific prompt patterns (code review, debugging, RAG queries)
+
+### Recommended
+
+- Standardizing message formats across multiple tools or agents
+- Embedding MCP resource content into prompt messages for context
+- Generating dynamic prompts that perform async lookups (knowledge base, APIs)
 
-Use `@Prompt` when you need to expose a reusable conversation template that an AI client can invoke with arguments. Prompts are ideal for code review patterns, debugging sessions, RAG queries, report generation, translation workflows, and any scenario where you want a standardized message structure.
+### Skip When
+
+- You need an executable action that performs work and returns results (see `create-tool`)
+- You need to expose read-only data at a URI (see `create-resource`)
+- The task requires autonomous multi-step reasoning with inner tools (see `create-agent`)
+
+> **Decision:** Use this skill when you need a reusable, parameterized conversation template that produces structured `GetPromptResult` messages.
 
 ## Class-Based Pattern
 
@@ -398,3 +392,45 @@ nx generate @frontmcp/nx:prompt
 ```
 
 This creates the prompt file, spec file, and updates barrel exports.
+
+## Common Patterns
+
+| Pattern             | Correct                                                           | Incorrect                                           | Why                                                                   |
+| ------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
+| Return type         | `execute()` returns `Promise<GetPromptResult>`                    | Returning a plain string or array of strings        | MCP protocol requires `{ messages: [...] }` structure                 |
+| Argument validation | Mark arguments as `required: true` in `arguments` array           | Manually checking `args.field` inside `execute()`   | Framework validates required arguments before `execute()` runs        |
+| Multi-turn priming  | Use `assistant` role messages to prime expected response patterns | Putting all instructions in a single `user` message | Alternating roles guides the LLM toward structured output             |
+| Resource embedding  | Use `type: 'resource'` content with a resource URI                | Inlining resource data as raw text in the prompt    | Resource references let clients resolve content dynamically           |
+| Error handling      | Use `this.fail(err)` for validation failures in execute           | `throw new Error(...)` directly                     | `this.fail` triggers the error flow with proper MCP error propagation |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Prompt class extends `PromptContext` and implements `execute(args)`
+- [ ] `@Prompt` decorator has `name` and `arguments` array with correct `required` flags
+- [ ] Prompt is registered in `prompts` array of `@App` or `@FrontMcp`
+- [ ] All required arguments have `required: true`
+
+### Runtime
+
+- [ ] Prompt appears in `prompts/list` MCP response
+- [ ] Calling prompt with valid arguments returns well-formed `GetPromptResult`
+- [ ] Missing required arguments trigger `MissingPromptArgumentError`
+- [ ] Multi-turn messages have correct `user`/`assistant` role alternation
+- [ ] DI dependencies resolve correctly via `this.get()`
+
+## Troubleshooting
+
+| Problem                                           | Cause                                               | Solution                                                                                  |
+| ------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Prompt not appearing in `prompts/list`            | Not registered in `prompts` array                   | Add prompt class to `@App` or `@FrontMcp` `prompts` array                                 |
+| `MissingPromptArgumentError` on optional argument | Argument marked `required: true` incorrectly        | Set `required: false` for optional arguments in the `arguments` array                     |
+| LLM ignores priming messages                      | Only using `user` role messages                     | Add `assistant` role messages to prime the conversation pattern                           |
+| Type error on `execute()` return                  | Returning plain string instead of `GetPromptResult` | Wrap return in `{ messages: [{ role: 'user', content: { type: 'text', text: '...' } }] }` |
+| `this.get(TOKEN)` throws DependencyNotFoundError  | Provider not registered in scope                    | Register provider in `providers` array of `@App` or `@FrontMcp`                           |
+
+## Reference
+
+- [Prompts Documentation](https://docs.agentfront.dev/frontmcp/servers/prompts)
+- Related skills: `create-tool`, `create-resource`, `create-agent`, `create-provider`

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

@@ -1,36 +1,28 @@
----
-name: create-provider
-description: Create dependency injection providers for database connections, API clients, and singleton services. Use when tools and resources need shared services, DB pools, or configuration objects.
-tags: [provider, di, dependency-injection, singleton, database, service]
-parameters:
-  - name: name
-    description: Provider name
-    type: string
-    required: true
-examples:
-  - scenario: Create a database connection pool provider
-    expected-outcome: Singleton DB pool injectable into all tools via this.get()
-  - scenario: Create a config provider from environment variables
-    expected-outcome: Type-safe config object available in any context
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/extensibility/providers
----
-
 # Creating Providers (Dependency Injection)
 
 Providers are singleton services — database pools, API clients, config objects — that tools, resources, prompts, and agents can access via `this.get(token)`.
 
-## When to Use
+## When to Use This Skill
+
+### Must Use
+
+- Multiple tools, resources, or agents need a shared database connection pool
+- API clients or external service connections must be singleton (not recreated per request)
+- You need lifecycle management with `onInit()` at startup and `onDestroy()` at shutdown
+
+### Recommended
+
+- Centralizing configuration values as a type-safe injectable object
+- Sharing a cache layer (Map, Redis) across all execution contexts
+- Providing environment-specific settings (API URLs, feature flags) via DI
 
-Create a provider when:
+### Skip When
 
-- Multiple tools need the same database connection pool
-- You have API clients that should be shared (not recreated per request)
-- Configuration values should be centralized and type-safe
-- You need lifecycle management (initialize on startup, cleanup on shutdown)
+- The service is only used by a single tool and has no lifecycle (inline it in the tool)
+- You need to build an executable action for AI clients (see `create-tool`)
+- You need autonomous LLM-driven orchestration (see `create-agent`)
+
+> **Decision:** Use this skill when you need a shared, singleton service with lifecycle management that tools, resources, and agents access via `this.get(token)`.
 
 ## Step 1: Define a Token
 
@@ -231,3 +223,46 @@ frontmcp dev
 # Call a tool that uses the provider
 # If provider fails to init, you'll see an error at startup
 ```
+
+## Common Patterns
+
+| Pattern            | Correct                                                                | Incorrect                                     | Why                                                                               |
+| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
+| Token definition   | `const DB: Token<DbService> = Symbol('DbService')` (typed Symbol)      | `const DB = 'database'` (string literal)      | Typed `Token<T>` enables compile-time type checking on `this.get()`               |
+| DI resolution      | `this.get(TOKEN)` with error handling                                  | `this.tryGet(TOKEN)!` with non-null assertion | `get` throws a clear `DependencyNotFoundError`; non-null assertions hide failures |
+| Lifecycle          | Use `onInit()` for async setup, `onDestroy()` for cleanup              | Initializing connections in the constructor   | Constructor runs synchronously; `onInit()` supports async operations              |
+| Registration scope | Register at `@App` level for app-scoped, `@FrontMcp` for server-scoped | Registering same provider in multiple apps    | Server-scoped providers are shared; duplicating causes multiple instances         |
+| Config provider    | `readonly` properties from `process.env`                               | Mutable properties that change at runtime     | Providers are singletons; mutable state can cause race conditions                 |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Provider class has `@Provider` decorator with `name`
+- [ ] Token is defined with `Token<T>` using a `Symbol` and typed interface
+- [ ] Provider is registered in `providers` array of `@App` or `@FrontMcp`
+- [ ] `onInit()` handles async setup (DB connections, API clients)
+- [ ] `onDestroy()` cleans up resources (close connections, flush buffers)
+
+### Runtime
+
+- [ ] Server starts without provider initialization errors
+- [ ] `this.get(TOKEN)` resolves the provider in tools, resources, and agents
+- [ ] Provider is a singleton (same instance across all contexts)
+- [ ] Server shutdown calls `onDestroy()` and cleans up resources
+- [ ] Missing provider throws `DependencyNotFoundError` with a clear message
+
+## Troubleshooting
+
+| Problem                              | Cause                                               | Solution                                                               |
+| ------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------- |
+| `DependencyNotFoundError` at runtime | Provider not registered in scope                    | Add provider to `providers` array in `@App` or `@FrontMcp`             |
+| Provider `onInit()` fails at startup | Missing environment variable or unreachable service | Check environment variables and service connectivity before starting   |
+| Multiple instances of same provider  | Registered in multiple apps instead of server level | Move to `@FrontMcp` `providers` for shared, server-scoped access       |
+| Type mismatch on `this.get(TOKEN)`   | Token typed with wrong interface                    | Ensure `Token<T>` generic matches the provider's implemented interface |
+| Provider not destroyed on shutdown   | Missing `onDestroy()` method                        | Implement `onDestroy()` to close connections and release resources     |
+
+## Reference
+
+- [Providers Documentation](https://docs.agentfront.dev/frontmcp/extensibility/providers)
+- Related skills: `create-tool`, `create-resource`, `create-agent`, `create-prompt`

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

@@ -1,38 +1,28 @@
----
-name: create-resource
-description: Create MCP resources and resource templates with URI-based access. Use when exposing data via URIs, creating resource templates, or serving dynamic content.
-tags: [resources, mcp, uri, templates, decorator]
-tools:
-  - name: create_resource
-    purpose: Scaffold a new resource or resource template class
-parameters:
-  - name: name
-    description: Resource name in kebab-case
-    type: string
-    required: true
-  - name: type
-    description: Whether to create a static resource or resource template
-    type: string
-    required: false
-examples:
-  - scenario: Create a static configuration resource
-    expected-outcome: Resource registered and readable via MCP at a fixed URI
-  - scenario: Create a resource template for user profiles
-    expected-outcome: Resource template with parameterized URI pattern
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/resources
----
-
 # Creating MCP Resources
 
 Resources expose data to AI clients through URI-based access following the MCP protocol. FrontMCP supports two kinds: **static resources** with fixed URIs (`@Resource`) and **resource templates** with parameterized URI patterns (`@ResourceTemplate`).
 
-## When to Use @Resource vs @ResourceTemplate
+## When to Use This Skill
+
+### Must Use
+
+- Exposing data to AI clients through URI-based access following the MCP protocol
+- Serving dynamic or static content that clients read on demand (config, status, files)
+- Creating parameterized URI patterns for families of related data (user profiles, repo files)
+
+### Recommended
+
+- Providing binary assets (images, PDFs) to AI clients via base64 blob encoding
+- Centralizing read-only data sources that multiple tools or prompts reference
+- Replacing ad-hoc tool responses with structured, cacheable resource URIs
 
-Use `@Resource` when the data lives at a single, known URI (e.g., `config://app/settings`, `status://server`). Use `@ResourceTemplate` when you need a family of related resources identified by parameters in the URI (e.g., `users://{userId}/profile`, `repo://{owner}/{repo}/files/{path}`).
+### Skip When
+
+- The client needs to perform an action, not read data (see `create-tool`)
+- You are building a reusable conversation template (see `create-prompt`)
+- The data requires autonomous multi-step reasoning to produce (see `create-agent`)
+
+> **Decision:** Use this skill when you need to expose readable data at a URI -- choose `@Resource` for a fixed URI or `@ResourceTemplate` for parameterized URI patterns.
 
 ## Static Resources with @Resource
 
@@ -435,3 +425,45 @@ nx generate @frontmcp/nx:resource
 ```
 
 This creates the resource file, spec file, and updates barrel exports.
+
+## Common Patterns
+
+| Pattern                | Correct                                                                  | Incorrect                                                               | Why                                                                              |
+| ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| URI scheme             | `uri: 'config://app/settings'` (valid scheme)                            | `uri: 'app-settings'` (no scheme)                                       | URIs are validated per RFC 3986; scheme-less URIs are rejected at registration   |
+| Resource vs template   | `@Resource` for fixed URIs, `@ResourceTemplate` for `{param}` URIs       | Using `@Resource` with `{param}` placeholders                           | Framework selects matching strategy based on decorator type                      |
+| Return shape           | Return full `ReadResourceResult` or let FrontMCP normalize plain objects | Manually wrapping every return in `{ contents: [...] }` when not needed | FrontMCP auto-wraps strings, objects, and arrays into valid `ReadResourceResult` |
+| Template params typing | `ResourceContext<{ userId: string }>` with typed `params`                | `ResourceContext` with untyped `params: Record<string, string>`         | Generic parameter enables compile-time checking of URI parameters                |
+| Binary content         | Use `blob` field with base64 encoding for binary data                    | Returning raw `Buffer` in `text` field                                  | MCP protocol expects base64 in `blob`; `text` is for string content only         |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Resource class extends `ResourceContext` and implements `execute(uri, params)`
+- [ ] `@Resource` has `name` and `uri` with a valid scheme, or `@ResourceTemplate` has `name` and `uriTemplate`
+- [ ] Resource is registered in `resources` array of `@App` or `@FrontMcp`
+- [ ] `mimeType` is set when the content type is not plain text
+
+### Runtime
+
+- [ ] Resource appears in `resources/list` MCP response
+- [ ] Reading the resource URI returns the expected `ReadResourceResult`
+- [ ] Template parameters are extracted correctly from the URI
+- [ ] Binary resources return valid base64 in the `blob` field
+- [ ] DI dependencies resolve correctly via `this.get()`
+
+## Troubleshooting
+
+| Problem                                          | Cause                                            | Solution                                                                           |
+| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Resource not appearing in `resources/list`       | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
+| URI validation error at startup                  | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
+| Template parameters are empty                    | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
+| Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
+| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
+
+## Reference
+
+- [Resources Documentation](https://docs.agentfront.dev/frontmcp/servers/resources)
+- Related skills: `create-tool`, `create-prompt`, `create-provider`, `create-agent`

package/catalog/{development/create-skill-with-tools/SKILL.md → frontmcp-development/references/create-skill-with-tools.md}

@@ -1,31 +1,28 @@
----
-name: create-skill-with-tools
-description: Create skills that reference and orchestrate MCP tools for multi-step workflows. Use when building skills with tool references, SKILL.md directories, or workflow instructions.
-tags: [skill, tools, workflow, instructions]
-parameters:
-  - name: name
-    description: Skill name in kebab-case
-    type: string
-    required: true
-examples:
-  - scenario: Create a deploy skill that uses build and test tools
-    expected-outcome: Skill guides AI through build, test, deploy workflow
-  - scenario: Create a skill from a SKILL.md file directory
-    expected-outcome: Skill loaded with instructions, scripts, references, assets
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/skills
----
-
 # Creating a Skill with Tools
 
 Skills are knowledge and workflow guides that help LLMs accomplish multi-step tasks using available MCP tools. Unlike tools (which execute actions directly) or agents (which run autonomous LLM loops), skills provide structured instructions, tool references, and context that the AI client uses to orchestrate tool calls on its own.
 
-## When to Use @Skill
+## When to Use This Skill
 
-Use `@Skill` when you want to teach an AI client HOW to accomplish a complex task by combining multiple tools in sequence. A skill does not execute anything itself -- it provides the instructions, tool references, and examples that guide the AI through a workflow.
+### Must Use
+
+- Teaching an AI client how to accomplish a complex task by combining multiple tools in a defined sequence
+- Building directory-based skills with `SKILL.md`, scripts, references, and assets loaded via `skillDir()`
+- Defining tool-orchestration instructions with explicit tool references, parameters, and examples
+
+### Recommended
+
+- Creating reusable workflow guides that can be discovered via HTTP (`/llm.txt`, `/skills`) or MCP protocol
+- Wrapping existing tools into a higher-level procedure with step-by-step instructions and validation modes
+- Providing AI clients with structured playbooks for incident response, deployment, or data-processing flows
+
+### Skip When
+
+- You need a single executable action with direct input/output (see `create-tool`)
+- You need an autonomous LLM loop that reasons across multiple steps on its own (see `create-agent`)
+- You are building a conversational template or system prompt without tool references (see `create-prompt`)
+
+> **Decision:** Use this skill when you need to guide an AI client through a multi-tool workflow using structured instructions and tool references, without executing anything directly.
 
 | Aspect     | @Skill                   | @Tool                | @Agent               |
 | ---------- | ------------------------ | -------------------- | -------------------- |
@@ -215,7 +212,7 @@ class RemoteWorkflowSkill extends SkillContext {}
 
 Use `skillDir()` to load a skill from a directory structure. The directory is expected to contain a `SKILL.md` file with frontmatter and instructions, plus optional subdirectories for scripts, references, and assets.
 
-```
+```text
 skills/
   deploy-service/
     SKILL.md           # Instructions with YAML frontmatter
@@ -577,3 +574,51 @@ class AuditApp {}
 })
 class AuditServer {}
 ```
+
+## Common Patterns
+
+| Pattern            | Correct                                                                               | Incorrect                                                      | Why                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Tool references    | `tools: [BuildTool, 'run_tests', { name: 'deploy', purpose: '...', required: true }]` | `tools: [{ class: BuildTool }]` (object with `class` key)      | The `tools` array accepts class refs, strings, or `{ name, purpose, required }` objects only |
+| Tool validation    | `toolValidation: 'strict'` for production skills                                      | Omitting `toolValidation` for critical workflows               | Default is `'warn'`; production skills should fail fast on missing tools with `'strict'`     |
+| Instruction source | `instructions: { file: './skills/deploy.md' }` for long content                       | Inlining hundreds of lines in the decorator string             | File-based instructions keep decorator metadata readable and instructions maintainable       |
+| Skill visibility   | `visibility: 'both'` (default) for public skills                                      | Setting `visibility: 'mcp'` when HTTP discovery is also needed | Skills with `'mcp'` visibility are hidden from `/llm.txt` and `/skills` HTTP endpoints       |
+| Parameter types    | `parameters: [{ name: 'env', type: 'string', required: true }]`                       | `parameters: { env: 'string' }` (plain object shape)           | Parameters must be an array of `{ name, description, type, required?, default? }` objects    |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@Skill` decorator has `name` and `description`
+- [ ] `instructions` are provided via inline string, `{ file }`, or `{ url }`
+- [ ] All tool references in `tools` array resolve to registered tools (when `toolValidation: 'strict'`)
+- [ ] Skill is registered in `skills` array of `@App` or `@FrontMcp`
+
+### Runtime
+
+- [ ] Skill appears in MCP skill listing (`skills/list`) when `visibility` includes `'mcp'`
+- [ ] Skill appears at `/llm.txt` and `/skills` HTTP endpoints when `visibility` includes `'http'`
+- [ ] `build()` returns complete `SkillContent` with instructions and tool references
+- [ ] `getToolRefs()` returns the correct list of resolved tool references
+- [ ] Hidden skills (`hideFromDiscovery: true`) are invocable but not listed in discovery
+
+### Directory-Based Skills
+
+- [ ] `SKILL.md` file exists at the root of the skill directory with valid YAML frontmatter
+- [ ] `skillDir()` correctly loads instructions, scripts, references, and assets
+- [ ] Frontmatter `tools` entries match registered tool names
+
+## Troubleshooting
+
+| Problem                                      | Cause                                                       | Solution                                                                               |
+| -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Skill not appearing in `/llm.txt`            | `visibility` is set to `'mcp'`                              | Change to `'both'` or `'http'` to include HTTP discovery                               |
+| `toolValidation: 'strict'` throws at startup | A referenced tool is not registered in the scope            | Register all referenced tools in the `tools` array of `@App` or `@FrontMcp`            |
+| `skillDir()` fails to load                   | `SKILL.md` file missing or frontmatter is invalid YAML      | Ensure the directory contains a `SKILL.md` with valid `---` delimited YAML frontmatter |
+| Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
+| Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |
+
+## Reference
+
+- [Skills Documentation](https://docs.agentfront.dev/frontmcp/servers/skills)
+- Related skills: `create-skill`, `create-tool`, `create-agent`, `create-prompt`