@frontmcp/skills 0.0.1 → 1.0.0-beta.10

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
 
-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:
+### Recommended
 
-- Coding style guides and conventions
-- Architecture decision records
-- Onboarding checklists
-- Deployment runbooks without automated steps
-- Review criteria and quality gates
+- 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
 
-If the skill needs to reference specific MCP tools, see the `create-skill-with-tools` skill instead.
+### Skip When
+
+- 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
 
@@ -111,17 +110,27 @@ class GitCommitGuideSkill extends SkillContext {}
 
 ### File Reference
 
-Load instructions from a Markdown file. The path is relative to the skill file location.
+Load instructions from a Markdown file. The path is resolved relative to the file that defines the skill (for both `@Skill` class decorators and `skill()` function calls).
 
 ```typescript
+// Class-based: path resolves relative to this file's directory
 @Skill({
   name: 'architecture-guide',
   description: 'System architecture overview and patterns',
   instructions: { file: './docs/architecture.md' },
 })
 class ArchitectureGuideSkill extends SkillContext {}
+
+// Function-based: same behavior — path resolves relative to this file's directory
+export default skill({
+  name: 'architecture-guide',
+  description: 'System architecture overview and patterns',
+  instructions: { file: './docs/architecture.md' },
+});
 ```
 
+> **Directory structure example:** If this file is at `src/skills/arch.skill.ts`, the instruction file should be at `src/skills/docs/architecture.md`.
+
 ### URL Reference
 
 Load instructions from a remote URL. Fetched at build time when the skill is loaded.
@@ -211,13 +220,26 @@ const CodeReviewChecklist = skill({
 
 Register it the same way as a class skill: `skills: [CodeReviewChecklist]`.
 
+The function builder also supports file-based instructions. Relative paths resolve from the file that calls `skill()`:
+
+```typescript
+// src/skills/deploy-guide.skill.ts
+import { skill } from '@frontmcp/sdk';
+
+export default skill({
+  name: 'deploy-guide',
+  description: 'Step-by-step deployment checklist',
+  instructions: { file: './docs/deploy-guide.md' }, // resolves to src/skills/docs/deploy-guide.md
+});
+```
+
 ## Directory-Based Skills with skillDir()
 
 Use `skillDir()` to load a skill from a directory containing a `SKILL.md` file with YAML frontmatter, plus optional subdirectories for scripts, references, and assets.
 
 ### Directory Structure
 
-```
+```text
 skills/
   coding-standards/
     SKILL.md           # Instructions with YAML frontmatter
@@ -448,7 +470,7 @@ import { Skill, SkillContext, FrontMcp, App, skill, skillDir } from '@frontmcp/s
 
 ## Step 1: Environment Setup
 1. Clone the repository
-2. Install Node.js 22+ and Yarn
+2. Install Node.js 24+ and Yarn
 3. Run \`yarn install\` to install dependencies
 4. Copy \`.env.example\` to \`.env\` and fill in values
 
@@ -524,3 +546,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`

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

@@ -1,28 +1,28 @@
----
-name: create-workflow
-description: Create multi-step workflows that connect jobs into managed execution pipelines with dependencies and conditions. Use when orchestrating sequential or parallel job execution.
-tags: [workflow, pipeline, orchestration, steps, jobs]
-priority: 6
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/workflows
----
-
 # Creating Workflows
 
 Workflows connect multiple jobs into managed execution pipelines with step dependencies, conditions, and triggers. A workflow defines a directed acyclic graph (DAG) of steps where each step runs a named job, and the framework handles ordering, parallelism, error propagation, and trigger management.
 
-## When to Use @Workflow
+## When to Use This Skill
+
+### Must Use
+
+- Orchestrating multiple jobs in a defined order with explicit step dependencies (e.g., build then test then deploy)
+- Building execution pipelines that require conditional branching, parallel fan-out, or diamond dependency patterns
+- Defining webhook- or event-triggered multi-step automation that the framework manages end to end
+
+### Recommended
 
-Use `@Workflow` when you need to orchestrate multiple jobs in a defined order with dependencies between them. Examples include:
+- CI/CD pipelines, data-processing ETL flows, or approval chains that combine three or more jobs
+- Multi-stage provisioning sequences where steps need `continueOnError` or per-step retry policies
+- Replacing hand-rolled orchestration code with a declarative DAG of job steps
 
-- CI/CD pipelines (build, test, deploy)
-- Data processing pipelines (extract, transform, load, verify)
-- Approval workflows (submit, review, approve, execute)
-- Multi-stage provisioning (create resources, configure, validate, notify)
+### Skip When
 
-If you only need a single background task, use a `@Job` instead. If you need real-time sequential tool calls guided by an AI, use a `@Skill`.
+- You only need a single background task with no inter-step dependencies (see `create-job`)
+- You need real-time, AI-guided sequential tool calls rather than pre-declared steps (see `create-skill-with-tools`)
+- You are building a conversational prompt template with no execution logic (see `create-prompt`)
+
+> **Decision:** Use this skill when you need a declarative, multi-step pipeline of jobs with dependency ordering, conditions, and managed error propagation.
 
 ## Class-Based Pattern
 
@@ -707,3 +707,45 @@ class CiApp {}
 })
 class CiServer {}
 ```
+
+## Common Patterns
+
+| Pattern           | Correct                                                            | Incorrect                                                          | Why                                                                             |
+| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Step dependencies | `dependsOn: ['build', 'test']` (array of step IDs)                 | `dependsOn: 'build'` (plain string)                                | `dependsOn` expects a `string[]`, not a single string                           |
+| Dynamic input     | `input: (steps) => ({ artifact: steps.get('build').outputs.url })` | `input: { artifact: buildResult.url }` (captured closure variable) | Static objects cannot reference previous step outputs; use the callback form    |
+| Conditional steps | `condition: (steps) => steps.get('test').state === 'completed'`    | `condition: (steps) => steps.get('test').outputs` (truthy check)   | Always check `.state` explicitly; outputs can be truthy even on partial failure |
+| Job registration  | Register all referenced jobs in the `jobs` array of `@App`         | Declare `jobName` in steps without registering the job class       | Steps reference jobs by name; unregistered jobs cause runtime lookup failures   |
+| Workflow trigger  | Set `trigger: 'webhook'` and provide `webhook: { path, secret }`   | Set `trigger: 'webhook'` without a `webhook` config object         | Webhook trigger requires the `webhook` configuration block for path and secret  |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@Workflow` decorator has `name` and at least one step in `steps`
+- [ ] Every `jobName` in steps matches a registered `@Job` name
+- [ ] `dependsOn` arrays reference valid step `id` values within the same workflow
+- [ ] No circular dependencies exist in the step DAG
+
+### Runtime
+
+- [ ] Workflow appears in the server's workflow registry after startup
+- [ ] Steps with no dependencies execute in parallel (up to `maxConcurrency`)
+- [ ] Conditional steps are correctly skipped or executed based on prior step results
+- [ ] `continueOnError: true` steps allow downstream steps to proceed on failure
+- [ ] Webhook-triggered workflows respond to incoming HTTP requests
+
+## Troubleshooting
+
+| Problem                                             | Cause                                                          | Solution                                                                                           |
+| --------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Step never executes                                 | `dependsOn` references a step ID that does not exist           | Verify all `dependsOn` entries match actual step `id` values in the workflow                       |
+| Workflow fails at startup with "job not found"      | `jobName` references an unregistered job                       | Add the job class to the `jobs` array in `@App` before registering the workflow                    |
+| Dynamic `input` callback receives undefined outputs | Dependent step was skipped or failed without `continueOnError` | Add a `condition` guard that checks `steps.get(id).state === 'completed'` before accessing outputs |
+| Webhook trigger does not fire                       | Missing or mismatched `webhook.secret`                         | Ensure `webhook.secret` matches the sender's HMAC secret and `webhook.path` is correct             |
+| Workflow exceeds timeout                            | Total step execution time exceeds the default 600000 ms        | Increase `timeout` at the workflow level or add per-step `timeout` overrides                       |
+
+## Reference
+
+- [Workflows Documentation](https://docs.agentfront.dev/frontmcp/servers/workflows)
+- Related skills: `create-job`, `create-skill-with-tools`, `create-tool`, `multi-app-composition`

package/catalog/{development/decorators-guide/SKILL.md → frontmcp-development/references/decorators-guide.md}

@@ -1,21 +1,10 @@
----
-name: decorators-guide
-description: Complete reference for all FrontMCP decorators and when to use each one. Use when choosing between decorators, understanding the architecture, or looking up decorator signatures.
-tags: [decorators, reference, architecture, guide]
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview
----
-
 # FrontMCP Decorators - Complete Reference
 
 ## Architecture Overview
 
 FrontMCP uses a hierarchical decorator system. The nesting order is:
 
-```
+```text
 @FrontMcp          (server root)
   +-- @App         (application module)
        +-- @Tool           (MCP tool)
@@ -35,6 +24,30 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 
 ---
 
+## When to Use This Skill
+
+### Must Use
+
+- You are building a new FrontMCP server and need to choose the correct decorator for each component
+- You are reviewing or debugging decorator configuration and need to verify field names, types, or nesting hierarchy
+- You are onboarding to the FrontMCP codebase and need a single reference for the full decorator architecture
+
+### Recommended
+
+- You are adding a new capability (tool, resource, prompt, agent, skill) to an existing server and want to confirm the correct decorator signature
+- You are designing a plugin or adapter and need to understand how it integrates with the decorator hierarchy
+- You are refactoring an app's module structure and need to verify which decorators belong in `@App` vs `@FrontMcp`
+
+### Skip When
+
+- You only need to write business logic inside an existing tool or resource (see `create-tool` reference)
+- You are configuring authentication or session management without changing decorators (see `configure-auth` reference)
+- You are working on CI/CD, deployment, or infrastructure that does not involve decorator choices
+
+> **Decision:** Use this skill whenever you need to look up, choose, or validate a FrontMCP decorator -- skip it when the decorator is already chosen and you are only implementing internal logic.
+
+---
+
 ## 1. @FrontMcp
 
 **Purpose:** Declares the root MCP server and its global configuration.
@@ -43,27 +56,28 @@ FrontMCP uses a hierarchical decorator system. The nesting order is:
 
 **Key fields:**
 
-| Field           | Description                                         |
-| --------------- | --------------------------------------------------- |
-| `info`          | Server name, version, and description               |
-| `apps`          | Array of `@App` classes to mount                    |
-| `redis?`        | Redis connection options                            |
-| `plugins?`      | Global plugins                                      |
-| `providers?`    | Global DI providers                                 |
-| `tools?`        | Standalone tools (outside apps)                     |
-| `resources?`    | Standalone resources                                |
-| `skills?`       | Standalone skills                                   |
-| `skillsConfig?` | Skills feature configuration (enabled, cache, auth) |
-| `transport?`    | Transport type (stdio, sse, streamable-http)        |
-| `http?`         | HTTP server options (port, host, cors)              |
-| `logging?`      | Logging configuration                               |
-| `elicitation?`  | Elicitation store config                            |
-| `sqlite?`       | SQLite storage config                               |
-| `pubsub?`       | Pub/sub configuration                               |
-| `jobs?`         | Job scheduler config                                |
-| `throttle?`     | Rate limiting config                                |
-| `pagination?`   | Pagination defaults                                 |
-| `ui?`           | UI configuration                                    |
+| Field           | Description                                                                     |
+| --------------- | ------------------------------------------------------------------------------- |
+| `info`          | Server name, version, and description                                           |
+| `apps`          | Array of `@App` classes to mount                                                |
+| `redis?`        | Redis connection options                                                        |
+| `plugins?`      | Global plugins                                                                  |
+| `providers?`    | Global DI providers                                                             |
+| `tools?`        | Standalone tools (outside apps)                                                 |
+| `resources?`    | Standalone resources                                                            |
+| `skills?`       | Standalone skills                                                               |
+| `skillsConfig?` | Skills feature configuration (enabled, cache, auth)                             |
+| `transport?`    | Transport preset ('modern', 'legacy', 'stateless-api', 'full') or config object |
+| `auth?`         | Authentication mode and OAuth configuration (AuthOptionsInput)                  |
+| `http?`         | HTTP server options (port, host, cors)                                          |
+| `logging?`      | Logging configuration                                                           |
+| `elicitation?`  | Elicitation store config                                                        |
+| `sqlite?`       | SQLite storage config                                                           |
+| `pubsub?`       | Pub/sub configuration                                                           |
+| `jobs?`         | Job scheduler config                                                            |
+| `throttle?`     | Rate limiting config                                                            |
+| `pagination?`   | Pagination defaults                                                             |
+| `ui?`           | UI configuration                                                                |
 
 ```typescript
 import { FrontMcp } from '@frontmcp/sdk';
@@ -71,7 +85,7 @@ import { FrontMcp } from '@frontmcp/sdk';
 @FrontMcp({
   info: { name: 'my-server', version: '1.0.0' },
   apps: [MainApp],
-  transport: 'streamable-http',
+  transport: 'modern', // Valid presets: 'modern', 'legacy', 'stateless-api', 'full'
   http: { port: 3000 },
   plugins: [RememberPlugin],
   skillsConfig: { enabled: true },
@@ -596,3 +610,78 @@ class AuditHooks {
 | `@Job`                      | `JobContext`      | `@App.jobs`      | Background task          |
 | `@Workflow`                 | -                 | `@App.workflows` | Multi-step orchestration |
 | `@Will/@Did/@Stage/@Around` | -                 | Entry class      | Lifecycle hooks          |
+
+---
+
+## Common Patterns
+
+| Pattern                     | Correct                                                                       | Incorrect                                                                    | Why                                                                                                                                                        |
+| --------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Grouping tools into modules | Place tools inside `@App({ tools: [...] })`                                   | Register tools directly in `@FrontMcp({ tools: [...] })` for large servers   | Apps provide logical grouping, scoped providers, and isolation; standalone tools in `@FrontMcp` are only appropriate for small servers or global utilities |
+| Exposing data to the LLM    | Use `@Resource` for fixed URIs, `@ResourceTemplate` for parameterized URIs    | Using `@Tool` to return static data that never changes                       | Resources are the MCP-standard way to expose readable data; tools are for actions with side effects or dynamic computation                                 |
+| Cross-cutting concerns      | Create a `@Plugin` with providers and context extensions                      | Adding logging/caching logic directly inside every tool's `execute()` method | Plugins centralize shared behavior, reduce duplication, and can be reused across servers                                                                   |
+| Background processing       | Use `@Job` with a cron schedule for recurring work                            | Using `setTimeout` or manual polling inside a tool                           | Jobs integrate with the scheduler, support persistence, and are visible in server diagnostics                                                              |
+| Multi-step orchestration    | Use `@Workflow` with ordered steps referencing `@Job` classes                 | Chaining multiple tool calls manually from the LLM                           | Workflows provide built-in ordering, error handling, and rollback semantics                                                                                |
+| Injecting services          | Use `@Provider` with `useFactory`/`useClass` and access via `this.get(Token)` | Importing singletons directly or using global state                          | DI providers support testability, lifecycle management, and per-scope isolation                                                                            |
+
+---
+
+## Verification Checklist
+
+### Structure
+
+- [ ] Server has exactly one `@FrontMcp` decorated class
+- [ ] Every `@App` is listed in the `@FrontMcp({ apps: [...] })` array
+- [ ] Each tool, resource, prompt, agent, and skill is registered in an `@App` (or in `@FrontMcp` for standalone use)
+
+### Decorator Fields
+
+- [ ] Every `@Tool` has `name`, `description`, and `inputSchema` defined
+- [ ] Every `@Resource` has `name` and `uri` with a valid scheme (e.g., `config://`, `file://`)
+- [ ] Every `@ResourceTemplate` has `uriTemplate` with `{param}` placeholders matching the `read()` params argument
+- [ ] Every `@Prompt` has `name` and at least one argument when it accepts input
+- [ ] Every `@Agent` has `name`, `description`, and `llm` configuration
+
+### Inheritance
+
+- [ ] Tool classes extend `ToolContext` and implement `execute()`
+- [ ] Prompt classes extend `PromptContext` and implement `execute()`
+- [ ] Resource classes extend `ResourceContext` and implement `read()`
+- [ ] Agent classes extend `AgentContext` and implement `execute()`
+- [ ] Job classes extend `JobContext` and implement `execute()`
+
+### Hooks
+
+- [ ] Hook flow strings match valid flows (e.g., `tools:call-tool`, `resources:read-resource`)
+- [ ] `@Around` hooks call `await next()` to continue the chain (unless intentionally short-circuiting)
+- [ ] Hooks do not mutate `rawInput` -- use `ctx.state.set()` for flow state
+
+### DI and Plugins
+
+- [ ] All `@Provider` entries specify exactly one of `useClass`, `useValue`, or `useFactory`
+- [ ] Plugins are registered in `@App({ plugins: [...] })` or `@FrontMcp({ plugins: [...] })`
+- [ ] Context extensions installed by plugins match the module augmentation declarations
+
+---
+
+## Troubleshooting
+
+| Problem                                            | Cause                                                                                                 | Solution                                                                                                                            |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Tool does not appear in `tools/list` MCP response  | Tool class is not registered in any `@App({ tools: [...] })` or `@FrontMcp({ tools: [...] })`         | Add the tool class to the `tools` array of the appropriate `@App` or `@FrontMcp` decorator                                          |
+| `this.get(Token)` throws `DependencyNotFoundError` | The provider for that token is not registered or is registered in a different app scope               | Add a `@Provider` for the token in the same `@App` or in `@FrontMcp({ providers: [...] })` for global access                        |
+| Resource returns 404 / `ResourceNotFoundError`     | The `uri` in `@Resource` does not match the requested URI, or `uriTemplate` parameters are misaligned | Verify the URI string exactly matches what the client requests; for templates, confirm `{param}` names match                        |
+| Hook never fires                                   | The `flow` string in `@Will`/`@Did`/`@Around`/`@Stage` does not match any registered flow             | Check the flow string against valid flows (e.g., `tools:call-tool`, `resources:read-resource`, `resources:list-resources`)          |
+| Plugin context extension is `undefined` at runtime | The plugin's `installContextExtension` function was not called, or module augmentation is missing     | Ensure the plugin is registered and its context extension function runs at startup; verify the `declare module` augmentation exists |
+| Agent `execute()` returns empty result             | LLM configuration is missing or invalid (wrong model name, missing API key)                           | Verify `llm.model` and `llm.provider` in `@Agent`, and ensure the provider API key is set in environment variables                  |
+
+---
+
+## Reference
+
+- **Official docs:** [FrontMCP Decorators Overview](https://docs.agentfront.dev/frontmcp/sdk-reference/decorators/overview)
+- **Related skills:**
+  - `create-tool` -- step-by-step guide for building tools with `@Tool` and `ToolContext`
+  - `create-resource` -- patterns for `@Resource` and `@ResourceTemplate` usage
+  - `create-plugin` -- creating plugins with `@Plugin`, providers, and context extensions
+  - `configure-auth` -- authentication and session configuration (not decorator-focused)