@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

@@ -1,29 +1,33 @@
 ---
 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
+description: Create instruction-only skills that package knowledge and workflow guides for AI clients
 ---
 
 # 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
 
-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:
+### Must Use
 
-- Coding style guides and conventions
-- Architecture decision records
-- Onboarding checklists
-- Deployment runbooks without automated steps
-- Review criteria and quality gates
+- 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
 
-If the skill needs to reference specific MCP tools, see the `create-skill-with-tools` skill instead.
+### Recommended
+
+- 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
+
+### 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
 
@@ -31,16 +35,23 @@ Create a class extending `SkillContext` and decorate it with `@Skill`. The decor
 
 ### SkillMetadata Fields
 
-| Field               | Type                                            | Required | Description                                                 |
-| ------------------- | ----------------------------------------------- | -------- | ----------------------------------------------------------- |
-| `name`              | `string`                                        | Yes      | Unique skill name in kebab-case                             |
-| `description`       | `string`                                        | Yes      | Short description of what the skill teaches                 |
-| `instructions`      | `string \| { file: string } \| { url: string }` | Yes      | The skill content -- see instruction sources below          |
-| `parameters`        | `SkillParameter[]`                              | No       | Customization parameters for the skill                      |
-| `examples`          | `SkillExample[]`                                | No       | Usage scenarios and expected outcomes                       |
-| `tags`              | `string[]`                                      | No       | Categorization tags for discovery                           |
-| `visibility`        | `'mcp' \| 'http' \| 'both'`                     | No       | Where the skill is discoverable (default: `'both'`)         |
-| `hideFromDiscovery` | `boolean`                                       | No       | Register but hide from listing endpoints (default: `false`) |
+| Field               | Type                                            | Required | Description                                                    |
+| ------------------- | ----------------------------------------------- | -------- | -------------------------------------------------------------- |
+| `name`              | `string`                                        | Yes      | Unique skill name in kebab-case (max 64 chars)                 |
+| `description`       | `string`                                        | Yes      | Short description (max 1024 chars, no HTML/XML)                |
+| `instructions`      | `string \| { file: string } \| { url: string }` | Yes      | The skill content -- see instruction sources below             |
+| `parameters`        | `SkillParameter[]`                              | No       | Customization parameters for the skill                         |
+| `examples`          | `SkillExample[]`                                | No       | Usage scenarios and expected outcomes                          |
+| `tags`              | `string[]`                                      | No       | Categorization tags for discovery                              |
+| `visibility`        | `'mcp' \| 'http' \| 'both'`                     | No       | Where the skill is discoverable (default: `'both'`)            |
+| `hideFromDiscovery` | `boolean`                                       | No       | Register but hide from listing endpoints (default: `false`)    |
+| `priority`          | `number`                                        | No       | Search ranking weight; higher = earlier (default: `0`)         |
+| `toolValidation`    | `'strict' \| 'warn' \| 'ignore'`                | No       | Behavior when referenced tools are missing (default: `'warn'`) |
+| `license`           | `string`                                        | No       | License identifier per Agent Skills spec (e.g., `'MIT'`)       |
+| `compatibility`     | `string`                                        | No       | Environment requirements (max 500 chars)                       |
+| `specMetadata`      | `Record<string, string>`                        | No       | Arbitrary key-value map (Agent Skills spec `metadata` field)   |
+| `allowedTools`      | `string`                                        | No       | Space-delimited pre-approved tool names (Agent Skills spec)    |
+| `resources`         | `SkillResources`                                | No       | Bundled dirs: `{ scripts?, references?, assets? }`             |
 
 ### Basic Example
 
@@ -111,17 +122,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 +232,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 +482,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 +558,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/references/tool-annotations.md → frontmcp-development/references/create-tool-annotations.md}

@@ -1,3 +1,8 @@
+---
+name: create-tool-annotations
+description: Reference for MCP tool annotation hints like readOnly, destructive, and idempotent
+---
+
 # Tool Annotations Reference
 
 Annotations provide hints to MCP clients about tool behavior:

package/catalog/{development/create-tool/references/output-schema-types.md → frontmcp-development/references/create-tool-output-schema-types.md}

@@ -1,3 +1,8 @@
+---
+name: create-tool-output-schema-types
+description: Reference for all supported outputSchema types including Zod shapes and JSON Schema
+---
+
 # Output Schema Types Reference
 
 All supported `outputSchema` types for `@Tool`:

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

@@ -1,34 +1,33 @@
 ---
 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
+description: Build MCP tools with Zod input/output validation and dependency injection
 ---
 
 # 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
 
-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.
+### 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
+
+### 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
 
@@ -73,7 +72,19 @@ class GreetUserTool extends ToolContext {
 - `this.output` -- the output (available after execute)
 - `this.metadata` -- tool metadata from the decorator
 - `this.scope` -- the current scope instance
-- `this.context` -- the execution context
+- `this.context` -- the execution context (see below)
+
+**`this.context` properties (FrontMcpContext):**
+
+| Property       | Type                | Description                         |
+| -------------- | ------------------- | ----------------------------------- |
+| `requestId`    | `string`            | Unique ID for this request          |
+| `sessionId`    | `string`            | Session identifier                  |
+| `scopeId`      | `string`            | Scope identifier                    |
+| `authInfo`     | `Partial<AuthInfo>` | Authentication info for the request |
+| `traceContext` | `TraceContext`      | Distributed tracing context         |
+| `timestamp`    | `number`            | Request timestamp                   |
+| `metadata`     | `RequestMetadata`   | Request headers, client IP, etc.    |
 
 ## Input Schema: Zod Raw Shapes
 
@@ -416,3 +427,141 @@ class ExpensiveOperationTool extends ToolContext {
   }
 }
 ```
+
+## Auth Providers
+
+Declare which auth providers a tool requires. Credentials are loaded before tool execution.
+
+```typescript
+// String shorthand — single provider
+@Tool({
+  name: 'create_issue',
+  description: 'Create a GitHub issue',
+  inputSchema: { title: z.string(), body: z.string() },
+  authProviders: ['github'],
+})
+class CreateIssueTool extends ToolContext {
+  /* ... */
+}
+
+// Full mapping — with scopes and required flag
+@Tool({
+  name: 'deploy_app',
+  description: 'Deploy to cloud',
+  inputSchema: { env: z.string() },
+  authProviders: [
+    { name: 'github', required: true, scopes: ['repo', 'workflow'] },
+    { name: 'aws', required: false, alias: 'cloud' },
+  ],
+})
+class DeployAppTool extends ToolContext {
+  /* ... */
+}
+```
+
+Auth provider mapping fields:
+
+- `name` — Provider name (must match a registered `@AuthProvider`)
+- `required?` — Whether credential is required (default: `true`)
+- `scopes?` — Required OAuth scopes
+- `alias?` — Alias for injection when using multiple providers
+
+## Elicitation (Interactive Input)
+
+Tools can request interactive input from users mid-execution using `this.elicit()`. Requires `elicitation` to be enabled at server level.
+
+```typescript
+@Tool({
+  name: 'confirm_delete',
+  description: 'Delete a resource after user confirmation',
+  inputSchema: { resourceId: z.string() },
+})
+class ConfirmDeleteTool extends ToolContext {
+  async execute(input: { resourceId: string }) {
+    const result = await this.elicit('Are you sure you want to delete this resource?', {
+      confirm: z.boolean().describe('Confirm deletion'),
+      reason: z.string().optional().describe('Reason for deletion'),
+    });
+
+    if (result.action === 'accept' && result.data.confirm) {
+      await this.get(ResourceService).delete(input.resourceId);
+      return 'Resource deleted';
+    }
+    return 'Deletion cancelled';
+  }
+}
+```
+
+> **Note:** Elicitation must be enabled at server level: `@FrontMcp({ elicitation: { enabled: true } })`. See `configure-elicitation` for full configuration options.
+
+## Tool Examples
+
+Provide usage examples for documentation and discovery:
+
+```typescript
+@Tool({
+  name: 'convert_currency',
+  description: 'Convert between currencies',
+  inputSchema: {
+    amount: z.number(),
+    from: z.string(),
+    to: z.string(),
+  },
+  examples: [
+    {
+      description: 'Convert USD to EUR',
+      input: { amount: 100, from: 'USD', to: 'EUR' },
+      output: { converted: 85.5, rate: 0.855 },
+    },
+    {
+      description: 'Convert with large amount',
+      input: { amount: 1_000_000, from: 'GBP', to: 'JPY' },
+    },
+  ],
+})
+class ConvertCurrencyTool 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,33 @@
 ---
 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
+description: Connect multiple jobs into managed DAG pipelines with dependencies, conditions, and triggers
 ---
 
 # 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
 
-Use `@Workflow` when you need to orchestrate multiple jobs in a defined order with dependencies between them. Examples include:
+### Must Use
 
-- 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)
+- 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
 
-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`.
+### Recommended
+
+- 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
+
+### Skip When
+
+- 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 +712,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`