@frontmcp/skills 0.0.1 → 1.0.0-beta.9

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`

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

@@ -1,29 +1,28 @@
----
-name: create-skill
-description: Create instruction-only skills that guide AI through workflows without tool references. Use when building knowledge packages, coding guidelines, or workflow templates.
-tags: [skill, instructions, knowledge, workflow, guide]
-priority: 7
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/skills
----
-
 # Creating Instruction-Only Skills
 
 Skills are knowledge and workflow packages that teach AI clients how to accomplish tasks. Unlike tools (which execute actions) or agents (which run autonomous LLM loops), a skill provides structured instructions that the AI follows on its own. An instruction-only skill contains no tool references -- it is purely a guide.
 
-## When to Use Instruction-Only Skills
+## When to Use This Skill
+
+### Must Use
+
+- You need to package knowledge, conventions, or workflow steps as a reusable skill that AI clients can follow
+- You are creating a SKILL.md catalog entry or a class/function-based skill with no tool dependencies
+- You want to enforce coding standards, onboarding steps, or review criteria through structured AI guidance
+
+### Recommended
 
-Use instruction-only skills when the goal is to transfer knowledge, enforce conventions, or define a workflow that the AI should follow using its own reasoning. Examples include:
+- You are building a deployment runbook, architecture decision record, or quality gate checklist
+- You want to share workflow templates across teams via MCP or HTTP discovery endpoints
+- You need parameterized instructions that callers can customize per invocation
 
-- Coding style guides and conventions
-- Architecture decision records
-- Onboarding checklists
-- Deployment runbooks without automated steps
-- Review criteria and quality gates
+### Skip When
 
-If the skill needs to reference specific MCP tools, see the `create-skill-with-tools` skill instead.
+- The skill must invoke MCP tools during execution -- use `create-skill-with-tools` instead
+- You need an autonomous agent loop rather than static instructions -- use an agent pattern instead
+- The content is a one-off prompt with no reuse value -- a plain prompt template is simpler
+
+> **Decision:** Pick this skill when you need a reusable, instruction-only knowledge package that guides AI through a workflow without requiring tool calls.
 
 ## Class-Based Pattern
 
@@ -217,7 +216,7 @@ Use `skillDir()` to load a skill from a directory containing a `SKILL.md` file w
 
 ### Directory Structure
 
-```
+```text
 skills/
   coding-standards/
     SKILL.md           # Instructions with YAML frontmatter
@@ -524,3 +523,55 @@ class OnboardingApp {}
 })
 class DevServer {}
 ```
+
+## Common Patterns
+
+| Pattern                             | Correct                                                | Incorrect                                                | Why                                                                                  |
+| ----------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Instruction source for short guides | `instructions: 'Use PascalCase for classes...'`        | Loading a one-paragraph guide from a separate file       | Inline strings keep short skills self-contained and easier to review                 |
+| Instruction source for long content | `instructions: { file: './docs/guide.md' }`            | Pasting 200+ lines as a template literal                 | File references keep the class readable and the content editable in Markdown tooling |
+| Skill naming                        | `name: 'api-design-guide'` (kebab-case)                | `name: 'ApiDesignGuide'` or `name: 'api design guide'`   | The `name` field must be kebab-case to match registry lookup and URL conventions     |
+| Visibility for internal runbooks    | `visibility: 'mcp'`                                    | `visibility: 'both'` for sensitive content               | Internal procedures should not be exposed on public HTTP endpoints like `/llm.txt`   |
+| Function builder for simple skills  | `const s = skill({ name, description, instructions })` | Creating a class with an empty body just to use `@Skill` | The function builder avoids boilerplate when no custom `build()` override is needed  |
+
+## Verification Checklist
+
+### Structure
+
+- [ ] Skill has a unique kebab-case `name`
+- [ ] `description` is a single sentence explaining what the skill teaches
+- [ ] `instructions` field is set (inline string, file reference, or URL reference)
+- [ ] No tool references appear in the instructions (instruction-only skill)
+
+### Metadata
+
+- [ ] `tags` array includes relevant categorization keywords
+- [ ] `visibility` is set appropriately (`'mcp'`, `'http'`, or `'both'`)
+- [ ] `parameters` have `name`, `description`, and `type` defined if present
+- [ ] `examples` include `scenario` and `expectedOutcome` if present
+
+### Registration
+
+- [ ] Skill class or function is added to the `skills` array in `@App` or `@FrontMcp`
+- [ ] Barrel export (`index.ts`) is updated if the skill is part of a publishable library
+- [ ] Test file (`*.spec.ts`) exists and covers metadata and build output
+
+### Discovery
+
+- [ ] Skill appears in `GET /skills` or MCP tool listing based on visibility setting
+- [ ] `hideFromDiscovery` is only set to `true` when the skill must be invoked by name only
+
+## Troubleshooting
+
+| Problem                                          | Cause                                                                   | Fix                                                                                    |
+| ------------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Skill does not appear in `/llm.txt` or `/skills` | `visibility` is set to `'mcp'` or `hideFromDiscovery` is `true`         | Set `visibility: 'both'` and `hideFromDiscovery: false`                                |
+| `loadInstructions()` returns empty string        | File reference path is wrong or the file is empty                       | Verify the path is relative to the skill file location and the target file has content |
+| `build()` throws "instructions required"         | The `instructions` field is missing or `undefined` in `@Skill` metadata | Provide an inline string, `{ file: '...' }`, or `{ url: '...' }`                       |
+| Skill parameters are ignored by the AI           | Parameters are declared but not referenced in the instruction text      | Mention each parameter by name in the instructions so the AI knows how to apply them   |
+| Directory-based skill missing bundled files      | Subdirectories are not named `scripts/`, `references/`, or `assets/`    | Use the exact conventional directory names; other names are not auto-bundled           |
+
+## Reference
+
+- **Docs:** <https://docs.agentfront.dev/frontmcp/servers/skills>
+- **Related skills:** `create-skill-with-tools` (skills that reference MCP tools), `setup-project` (project scaffolding workflows)

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

@@ -1,34 +1,28 @@
----
-name: create-tool
-description: Create and register an MCP tool with Zod input validation and typed output. Use when building tools, defining input schemas, adding output validation, or registering tools in an app.
-tags: [tools, mcp, zod, schema, decorator]
-tools:
-  - name: create_tool
-    purpose: Scaffold a new tool class
-parameters:
-  - name: name
-    description: Tool name in snake_case
-    type: string
-    required: true
-examples:
-  - scenario: Create a calculator tool with add operation
-    expected-outcome: Tool registered and callable via MCP
-  - scenario: Create a tool with DI and error handling
-    expected-outcome: Tool using providers and proper error classes
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/tools
----
-
 # Creating an MCP Tool
 
 Tools are the primary way to expose executable actions to AI clients in the MCP protocol. In FrontMCP, tools are TypeScript classes that extend `ToolContext`, decorated with `@Tool`, and registered on a `@FrontMcp` server or inside an `@App`.
 
-## When to Use @Tool
+## When to Use This Skill
+
+### Must Use
+
+- Building a new executable action that AI clients can invoke via MCP
+- Defining typed input schemas with Zod validation for tool parameters
+- Adding output schema validation to prevent data leaks from tool responses
+
+### Recommended
+
+- Adding rate limiting, concurrency control, or timeouts to existing tools
+- Integrating dependency injection into tool execution
+- Converting raw function handlers into class-based `ToolContext` patterns
 
-Use `@Tool` when you need to expose an action that an AI client can invoke. Tools accept validated input, perform work (database queries, API calls, computations), and return structured results. Every tool goes through Zod-based input validation before `execute()` runs.
+### Skip When
+
+- Exposing read-only data that does not require execution logic (see `create-resource`)
+- Building conversational templates or system prompts (see `create-prompt`)
+- Orchestrating multi-tool workflows with conditional logic (see `create-agent`)
+
+> **Decision:** Use this skill when you need an AI-callable action that accepts validated input, performs work, and returns structured output.
 
 ## Class-Based Pattern
 
@@ -416,3 +410,45 @@ class ExpensiveOperationTool extends ToolContext {
   }
 }
 ```
+
+## Common Patterns
+
+| Pattern        | Correct                                         | Incorrect                                     | Why                                                           |
+| -------------- | ----------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| Input schema   | `inputSchema: { name: z.string() }` (raw shape) | `inputSchema: z.object({ name: z.string() })` | Framework wraps in `z.object()` internally                    |
+| Output schema  | Always define `outputSchema`                    | Omit `outputSchema`                           | Prevents data leaks and enables CodeCall chaining             |
+| DI resolution  | `this.get(TOKEN)` with proper error handling    | `this.tryGet(TOKEN)!` with non-null assertion | `get` throws a clear error; non-null assertions mask failures |
+| Error handling | `this.fail(new ResourceNotFoundError(...))`     | `throw new Error(...)`                        | `this.fail` triggers the error flow with MCP error codes      |
+| Tool naming    | `snake_case` names: `get_weather`               | `camelCase` or `PascalCase`: `getWeather`     | MCP protocol convention for tool names                        |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Tool class extends `ToolContext` and implements `execute()`
+- [ ] `@Tool` decorator has `name`, `description`, and `inputSchema`
+- [ ] `outputSchema` is defined to validate and restrict output fields
+- [ ] Tool is registered in `tools` array of `@App` or `@FrontMcp`
+
+### Runtime
+
+- [ ] Tool appears in `tools/list` MCP response
+- [ ] Valid input returns expected output
+- [ ] Invalid input returns Zod validation error (not a crash)
+- [ ] `this.fail()` triggers proper MCP error response
+- [ ] DI dependencies resolve correctly via `this.get()`
+
+## Troubleshooting
+
+| Problem                                          | Cause                                       | Solution                                                                     |
+| ------------------------------------------------ | ------------------------------------------- | ---------------------------------------------------------------------------- |
+| Tool not appearing in `tools/list`               | Not registered in `tools` array             | Add tool class to `@App` or `@FrontMcp` `tools` array                        |
+| Zod validation error on valid input              | Using `z.object()` wrapper in `inputSchema` | Use raw shape: `{ field: z.string() }` not `z.object({ field: z.string() })` |
+| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope            | Register provider in `providers` array of `@App` or `@FrontMcp`              |
+| Output contains unexpected fields                | No `outputSchema` defined                   | Add `outputSchema` to strip unvalidated fields from response                 |
+| Tool times out                                   | No timeout configured for long operation    | Add `timeout: { executeMs: 30_000 }` to `@Tool` options                      |
+
+## Reference
+
+- [Tools Documentation](https://docs.agentfront.dev/frontmcp/servers/tools)
+- Related skills: `create-resource`, `create-prompt`, `configure-throttle`, `create-agent`