@frontmcp/skills 0.0.1 → 1.0.0-beta.11

package/catalog/frontmcp-development/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: frontmcp-development
+description: 'Use when you want to create a tool, add a resource, build a prompt, write a provider, implement an adapter, add OpenAPI integration, create a plugin, agent, job, or workflow. The skill for BUILDING any FrontMCP component.'
+tags: [router, development, tools, resources, prompts, agents, skills, guide]
+category: development
+targets: [all]
+bundle: [recommended, minimal, full]
+priority: 10
+visibility: both
+license: Apache-2.0
+metadata:
+  docs: https://docs.agentfront.dev/frontmcp/servers/overview
+---
+
+# FrontMCP Development Router
+
+Entry point for building MCP server components. This skill helps you find the right development skill based on what you want to build. It does not teach implementation details itself — it routes you to the specific skill that does.
+
+## When to Use This Skill
+
+### Must Use
+
+- Starting a FrontMCP development task and unsure which component type to build (tool vs resource vs prompt vs agent)
+- Onboarding to the FrontMCP development model and need an overview of all building blocks
+- Planning a feature that may require multiple component types working together
+
+### Recommended
+
+- Looking up the canonical name of a development skill to install or search
+- Comparing component types to decide which fits your use case
+- Understanding how tools, resources, prompts, agents, and skills relate to each other
+
+### Skip When
+
+- You already know which component to build (go directly to `create-tool`, `create-resource`, etc.)
+- You need to configure server settings, not build components (see `frontmcp-config`)
+- You need to deploy or build, not develop (see `frontmcp-deployment`)
+
+> **Decision:** Use this skill when you need to figure out WHAT to build. Use the specific skill when you already know.
+
+## Scenario Routing Table
+
+| Scenario                                                 | Skill                             | Description                                                                                   |
+| -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
+| Expose an executable action that AI clients can call     | `create-tool`                     | Class-based or function-style tools with Zod input/output validation                          |
+| Expose read-only data via a URI                          | `create-resource`                 | Static resources or URI template resources for dynamic data                                   |
+| Create a reusable conversation template or system prompt | `create-prompt`                   | Prompt entries with arguments and multi-turn message sequences                                |
+| Build an autonomous AI loop that orchestrates tools      | `create-agent`                    | Agent entries with LLM config, inner tools, and swarm handoff                                 |
+| Register shared services or configuration via DI         | `create-provider`                 | Dependency injection tokens, lifecycle hooks, factory providers                               |
+| Run a background task with progress and retries          | `create-job`                      | Job entries with attempt tracking, retry config, and progress                                 |
+| Chain multiple jobs into a sequential pipeline           | `create-workflow`                 | Workflow entries that compose jobs with data passing                                          |
+| Write instruction-only AI guidance (no code execution)   | `create-skill`                    | Skill entries with markdown instructions from files, strings, or URLs                         |
+| Write AI guidance that also orchestrates tools           | `create-skill-with-tools`         | Skill entries that combine instructions with registered tools                                 |
+| Look up any decorator signature or option                | `decorators-guide`                | Complete reference for @Tool, @Resource, @Prompt, @Agent, @App, @FrontMcp, and more           |
+| Integrate an external API via OpenAPI spec               | `official-adapters`               | OpenapiAdapter with auth, polling, inline specs, and multiple API composition                 |
+| Use official plugins (caching, remember, feature flags)  | `official-plugins`                | Built-in plugins for caching, session memory, approval, and feature flags (dashboard is beta) |
+| Connect to an external data source via a custom adapter  | `create-adapter`                  | Create custom adapters for external data sources                                              |
+| Configure LLM settings for an agent component            | `create-agent-llm-config`         | Configure LLM settings for agent components                                                   |
+| Add will/did/around lifecycle hooks to a plugin          | `create-plugin-hooks`             | Add lifecycle hooks to plugins (will/did/around)                                              |
+| Annotate tools with client hints for AI clients          | `create-tool-annotations`         | Add MCP tool annotations for client hints                                                     |
+| Define typed output schemas for tool responses           | `create-tool-output-schema-types` | Define typed output schemas for tools                                                         |
+
+## Recommended Reading Order
+
+1. **`decorators-guide`** — Start here to understand the full decorator landscape
+2. **`create-tool`** — The most common building block; learn tools first
+3. **`create-resource`** — Expose data alongside tools
+4. **`create-prompt`** — Add reusable conversation templates
+5. **`create-provider`** — Share services across tools and resources via DI
+6. **`create-agent`** — Build autonomous AI loops (advanced)
+7. **`create-job`** / **`create-workflow`** — Background processing (advanced)
+8. **`create-skill`** / **`create-skill-with-tools`** — Author your own skills (meta)
+9. **`official-adapters`** — Integrate external APIs via OpenAPI specs
+10. **`official-plugins`** — Add caching, session memory, feature flags, and more
+
+## Cross-Cutting Patterns
+
+| Pattern           | Applies To                        | Rule                                                                                   |
+| ----------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
+| Naming convention | Tools                             | Use `snake_case` for tool names (`get_weather`, not `getWeather`)                      |
+| Naming convention | Skills, resources                 | Use `kebab-case` for skill and resource names                                          |
+| File naming       | All components                    | Use `<name>.<type>.ts` pattern (e.g., `fetch-weather.tool.ts`)                         |
+| DI access         | Tools, resources, prompts, agents | Use `this.get(TOKEN)` (throws) or `this.tryGet(TOKEN)` (returns undefined)             |
+| Error handling    | All components                    | Use `this.fail(err)` with MCP error classes, not raw `throw`                           |
+| Input validation  | Tools                             | Always use Zod raw shapes (not `z.object()`) for `inputSchema`                         |
+| Output validation | Tools                             | Always define `outputSchema` to prevent data leaks                                     |
+| Registration      | All components                    | Add to `tools`, `resources`, `prompts`, `agents`, etc. arrays in `@App` or `@FrontMcp` |
+| Test files        | All components                    | Use `.spec.ts` extension, never `.test.ts`                                             |
+
+## Common Patterns
+
+| Pattern                 | Correct                                                   | Incorrect                                                | Why                                                                   |
+| ----------------------- | --------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
+| Choosing component type | Tool for actions, Resource for data, Prompt for templates | Using a tool to return static data                       | Each type has protocol-level semantics; misuse confuses AI clients    |
+| Component registration  | Register in `@App` arrays, compose apps in `@FrontMcp`    | Register tools directly in `@FrontMcp` without an `@App` | Apps provide modularity; direct registration bypasses app-level hooks |
+| Shared logic            | Extract to a `@Provider` and inject via DI                | Duplicate code across multiple tools                     | Providers are testable, lifecycle-managed, and scoped                 |
+| Complex orchestration   | Use `@Agent` with inner tools                             | Chain tool calls manually in a single tool               | Agents handle LLM loops, retries, and tool selection automatically    |
+| Background work         | Use `@Job` with retry config                              | Run long tasks inside a tool's `execute()`               | Jobs have progress tracking, attempt awareness, and timeout handling  |
+
+## Verification Checklist
+
+### Architecture
+
+- [ ] Each component type matches its semantic purpose (action=tool, data=resource, template=prompt)
+- [ ] Shared services use `@Provider` with DI tokens, not module-level singletons
+- [ ] Components are registered in `@App` arrays, apps composed in `@FrontMcp`
+
+### Development Workflow
+
+- [ ] Files follow `<name>.<type>.ts` naming convention
+- [ ] Each component has a corresponding `.spec.ts` test file
+- [ ] `decorators-guide` consulted for unfamiliar decorator options
+
+## Troubleshooting
+
+| Problem                                  | Cause                                          | Solution                                                                                                                    |
+| ---------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Unsure which component type to use       | Requirements are ambiguous                     | Check the Scenario Routing Table above; if the action modifies state, use a tool; if it returns data by URI, use a resource |
+| Component not discovered at runtime      | Not registered in `@App` or `@FrontMcp` arrays | Add to the appropriate array (`tools`, `resources`, `prompts`, etc.)                                                        |
+| DI token not resolving                   | Provider not registered in scope               | Register the provider in the `providers` array of the same `@App`                                                           |
+| Need both AI guidance and tool execution | Used `create-skill` but need tools too         | Switch to `create-skill-with-tools` which combines instructions with registered tools                                       |
+
+## Reference
+
+- [Server Overview](https://docs.agentfront.dev/frontmcp/servers/overview)
+- Related skills: `create-tool`, `create-resource`, `create-prompt`, `create-agent`, `create-provider`, `create-job`, `create-workflow`, `create-skill`, `create-skill-with-tools`, `decorators-guide`, `official-adapters`, `official-plugins`

package/catalog/frontmcp-development/references/create-adapter.md

@@ -0,0 +1,170 @@
+---
+name: create-adapter
+description: Build adapters that generate MCP tools and resources from external sources automatically
+---
+
+# Creating Custom Adapters
+
+Build adapters that automatically generate MCP tools, resources, and prompts from external sources — databases, GraphQL schemas, proprietary APIs, or any definition format.
+
+## When to Use This Skill
+
+### Must Use
+
+- Integrating a non-OpenAPI source (GraphQL, gRPC, database schema) that should generate MCP tools automatically
+- Building a reusable adapter that converts external definitions into tools, resources, or prompts at startup
+- Creating tools dynamically at runtime based on external state or configuration
+
+### Recommended
+
+- Wrapping a proprietary internal API that has its own schema format
+- Auto-generating tools from a database schema or config file on server start
+- Building an adapter that polls an external source and refreshes tool definitions periodically
+
+### Skip When
+
+- The external API has an OpenAPI/Swagger spec (see `official-adapters`)
+- You need cross-cutting middleware behavior like logging or caching (see `create-plugin`)
+- You are building a single static tool manually (see `create-tool`)
+
+> **Decision:** Use this skill when you need to auto-generate MCP tools, resources, or prompts from a non-OpenAPI external source by extending `DynamicAdapter`.
+
+## Step 1: Extend DynamicAdapter
+
+```typescript
+import { DynamicAdapter, type FrontMcpAdapterResponse } from '@frontmcp/sdk';
+
+interface MyAdapterOptions {
+  endpoint: string;
+  apiKey: string;
+}
+
+class MyApiAdapter extends DynamicAdapter<MyAdapterOptions> {
+  declare __options_brand: MyAdapterOptions;
+
+  async fetch(): Promise<FrontMcpAdapterResponse> {
+    // Fetch definitions from external source
+    const res = await globalThis.fetch(this.options.endpoint, {
+      headers: { Authorization: `Bearer ${this.options.apiKey}` },
+    });
+    const schema = await res.json();
+
+    // Convert to MCP tool definitions
+    return {
+      tools: schema.operations.map((op: { name: string; description: string; params: Record<string, unknown> }) => ({
+        name: op.name,
+        description: op.description,
+        inputSchema: this.convertParams(op.params),
+        execute: async (input: Record<string, unknown>) => {
+          return this.callApi(op.name, input);
+        },
+      })),
+      resources: [],
+      prompts: [],
+    };
+  }
+
+  private convertParams(params: Record<string, unknown>) {
+    // Convert external param definitions to Zod schemas
+    // ...
+  }
+
+  private async callApi(operation: string, input: Record<string, unknown>) {
+    // Call the external API
+    // ...
+  }
+}
+```
+
+## Step 2: Register
+
+```typescript
+@App({
+  name: 'MyApp',
+  adapters: [
+    MyApiAdapter.init({
+      name: 'my-api',
+      endpoint: 'https://api.example.com/schema',
+      apiKey: process.env.API_KEY!,
+    }),
+  ],
+})
+class MyApp {}
+```
+
+## FrontMcpAdapterResponse
+
+The `fetch()` method returns tools, resources, and prompts to register:
+
+```typescript
+interface FrontMcpAdapterResponse {
+  tools?: AdapterToolDefinition[];
+  resources?: AdapterResourceDefinition[];
+  prompts?: AdapterPromptDefinition[];
+}
+```
+
+## Static init()
+
+`DynamicAdapter` provides a static `init()` method inherited by all subclasses:
+
+```typescript
+// Usage — no manual instantiation needed
+const adapter = MyApiAdapter.init({
+  name: 'my-api',        // Required: adapter name (used for tool namespacing)
+  endpoint: '...',
+  apiKey: '...',
+});
+
+// Register in @App
+@App({ adapters: [adapter] })
+```
+
+## Nx Generator
+
+```bash
+nx generate @frontmcp/nx:adapter my-adapter --project=my-app
+```
+
+Creates a `DynamicAdapter` subclass in `src/adapters/my-adapter.adapter.ts`.
+
+## Common Patterns
+
+| Pattern                 | Correct                                                       | Incorrect                                              | Why                                                                             |
+| ----------------------- | ------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Adapter registration    | `MyAdapter.init({ name: 'my-api', ... })` in `adapters` array | `new MyAdapter({ ... })` directly                      | `init()` returns the proper provider entry for DI wiring                        |
+| Options branding        | `declare __options_brand: MyAdapterOptions;` in adapter class | Omitting the brand declaration                         | Brand ensures TypeScript infers the correct options type for `init()`           |
+| Fetch return type       | Return `{ tools: [...], resources: [...], prompts: [...] }`   | Returning raw API response without conversion          | `fetch()` must return `FrontMcpAdapterResponse` with MCP-compatible definitions |
+| Tool naming             | Namespace tools: `name: 'my-api:operation-name'`              | Flat names without namespace: `name: 'operation-name'` | Namespacing prevents collisions when multiple adapters are registered           |
+| Error handling in fetch | Throw descriptive errors with endpoint info                   | Silently returning empty arrays on failure             | Adapter errors should surface at startup so misconfigurations are caught early  |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Adapter class extends `DynamicAdapter<TOptions>`
+- [ ] `__options_brand` is declared with the correct options type
+- [ ] `fetch()` method is implemented and returns `FrontMcpAdapterResponse`
+- [ ] Adapter is registered via `.init()` in the `adapters` array of `@App`
+
+### Runtime
+
+- [ ] Generated tools appear in `tools/list` MCP response
+- [ ] Tool names are namespaced with the adapter name (e.g., `my-api:operationId`)
+- [ ] Generated tools accept valid input and return expected output
+- [ ] Adapter fetch errors produce clear startup error messages
+
+## Troubleshooting
+
+| Problem                                    | Cause                                                       | Solution                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| No tools appear after adapter registration | `fetch()` returns empty `tools` array                       | Verify external source is reachable and response is parsed correctly             |
+| TypeScript error on `.init()` options      | Missing `__options_brand` declaration                       | Add `declare __options_brand: MyAdapterOptions;` to the adapter class            |
+| Tool input validation fails                | `inputSchema` conversion does not produce valid Zod schemas | Verify `convertParams` produces `z.object()` shapes matching the external schema |
+| Duplicate tool name error                  | Multiple adapters produce tools with the same name          | Use unique `name` parameter in `init()` to namespace tools                       |
+| Adapter not found at runtime               | Registered in wrong `@App` or not in `adapters` array       | Ensure `.init()` result is in the `adapters` array of the correct `@App`         |
+
+## Reference
+
+- [Adapter Documentation](https://docs.agentfront.dev/frontmcp/adapters/overview)
+- Related skills: `official-adapters`, `create-plugin`, `create-tool`

package/catalog/{development/create-agent/references/llm-config.md → frontmcp-development/references/create-agent-llm-config.md}

@@ -1,13 +1,18 @@
+---
+name: create-agent-llm-config
+description: Reference for supported LLM provider configurations including Anthropic and OpenAI
+---
+
 # Agent LLM Configuration Reference
 
-## Supported Adapters
+## Supported Providers
 
 ### Anthropic
 
 ```typescript
 llm: {
-  adapter: 'anthropic',
-  model: 'claude-sonnet-4-20250514',
+  provider: 'anthropic', // Any supported provider — 'anthropic', 'openai', etc.
+  model: 'claude-sonnet-4-20250514', // Any supported model for the chosen provider
   apiKey: { env: 'ANTHROPIC_API_KEY' },
   maxTokens: 4096,
 }
@@ -17,8 +22,8 @@ llm: {
 
 ```typescript
 llm: {
-  adapter: 'openai',
-  model: 'gpt-4o',
+  provider: 'openai',
+  model: 'gpt-4o', // Any supported model for the chosen provider
   apiKey: { env: 'OPENAI_API_KEY' },
   maxTokens: 4096,
 }

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

@@ -1,35 +1,35 @@
 ---
 name: create-agent
-description: Create autonomous AI agents with inner tools, LLM providers, and multi-agent swarms. Use when building agents, configuring LLM adapters, adding inner tools, or setting up agent handoff.
-tags: [agent, ai, llm, tools, autonomous]
-parameters:
-  - name: llm-provider
-    description: LLM provider to use
-    type: string
-    default: anthropic
-  - name: name
-    description: Agent name
-    type: string
-    required: true
-examples:
-  - scenario: Create a code review agent with GitHub tools
-    expected-outcome: Agent autonomously reviews PRs using inner tools
-  - scenario: Create a multi-agent swarm for complex workflows
-    expected-outcome: Agents hand off tasks to each other
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/agents
+description: Create autonomous AI agents that use LLM reasoning to plan and invoke inner tools
 ---
 
 # Creating an Autonomous Agent
 
 Agents are autonomous AI entities that use an LLM to reason, plan, and invoke inner tools to accomplish goals. In FrontMCP, agents are TypeScript classes that extend `AgentContext`, decorated with `@Agent`, and registered on a `@FrontMcp` server or inside an `@App`.
 
-## When to Use @Agent vs @Tool
+## When to Use This Skill
 
-Use `@Agent` when the task requires autonomous reasoning, multi-step planning, or LLM-driven decision making. An agent receives a goal, decides which tools to call, interprets results, and iterates until the goal is met. Use `@Tool` when you need a direct, deterministic function that executes a single action without LLM involvement.
+### Must Use
+
+- Building an autonomous AI entity that uses LLM reasoning to decide which tools to call
+- Orchestrating multi-step workflows where the agent plans, acts, and iterates toward a goal
+- Creating multi-agent swarms with handoff between specialized agents
+
+### Recommended
+
+- Performing complex tasks that require chaining multiple inner tools with LLM-driven decisions
+- Implementing structured multi-pass review (security pass, quality pass, synthesis)
+- Composing nested sub-agents with different LLM configs for specialized subtasks
+
+### Skip When
+
+- You need a direct, deterministic function that executes a single action (see `create-tool`)
+- You are building a reusable conversation template without autonomous execution (see `create-prompt`)
+- You only need to expose readable data at a URI (see `create-resource`)
+
+> **Decision:** Use this skill when the task requires autonomous LLM-driven reasoning, tool invocation, and iterative planning -- not a single deterministic action.
+
+### @Agent vs @Tool Quick Comparison
 
 | Aspect          | @Agent                          | @Tool                        |
 | --------------- | ------------------------------- | ---------------------------- |
@@ -50,8 +50,8 @@ import { z } from 'zod';
   name: 'code_reviewer',
   description: 'Reviews code changes and provides feedback',
   llm: {
-    adapter: 'anthropic',
-    model: 'claude-sonnet-4-20250514',
+    provider: 'anthropic', // Any supported provider — 'anthropic', 'openai', etc.
+    model: 'claude-sonnet-4-20250514', // Any supported model for the chosen provider
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
   inputSchema: {
@@ -110,7 +110,7 @@ The `llm` field is required and configures which LLM provider and model the agen
   name: 'my_agent',
   description: 'An agent with LLM config',
   llm: {
-    adapter: 'anthropic',          // 'anthropic' or 'openai'
+    provider: 'anthropic',          // 'anthropic' or 'openai'
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' }, // read from env var
   },
@@ -122,7 +122,7 @@ The `apiKey` field accepts either an object `{ env: 'ENV_VAR_NAME' }` to read fr
 ```typescript
 // OpenAI example
 llm: {
-  adapter: 'openai',
+  provider: 'openai',
   model: 'gpt-4o',
   apiKey: { env: 'OPENAI_API_KEY' },
 },
@@ -139,7 +139,7 @@ Override `execute()` when you need custom orchestration logic:
   name: 'structured_reviewer',
   description: 'Reviews code with a structured multi-pass approach',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -193,7 +193,7 @@ Use `completion()` for a single LLM call that returns the full response, and `st
   name: 'summarizer',
   description: 'Summarizes text using LLM',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -287,7 +287,7 @@ class PostReviewCommentTool extends ToolContext {
   name: 'pr_reviewer',
   description: 'Autonomously reviews GitHub pull requests',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -315,7 +315,7 @@ Use `exports: { tools: [] }` to expose specific tools that the agent makes avail
   name: 'data_pipeline',
   description: 'Data processing pipeline agent',
   llm: {
-    adapter: 'openai',
+    provider: 'openai',
     model: 'gpt-4o',
     apiKey: { env: 'OPENAI_API_KEY' },
   },
@@ -333,7 +333,7 @@ Use the `agents` array to compose agents from smaller, specialized sub-agents. E
 @Agent({
   name: 'security_auditor',
   description: 'Audits code for security vulnerabilities',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   systemInstructions: 'Focus on OWASP Top 10 vulnerabilities.',
   tools: [StaticAnalysisTool],
 })
@@ -342,7 +342,7 @@ class SecurityAuditorAgent extends AgentContext {}
 @Agent({
   name: 'performance_auditor',
   description: 'Audits code for performance issues',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   systemInstructions: 'Focus on time complexity, memory leaks, and N+1 queries.',
   tools: [ProfilerTool],
 })
@@ -351,7 +351,7 @@ class PerformanceAuditorAgent extends AgentContext {}
 @Agent({
   name: 'code_auditor',
   description: 'Comprehensive code auditor that delegates to specialized sub-agents',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   inputSchema: {
     repository: z.string().describe('Repository URL'),
     branch: z.string().default('main').describe('Branch to audit'),
@@ -372,7 +372,7 @@ Swarm mode enables multi-agent handoff, where agents can transfer control to eac
 @Agent({
   name: 'triage_agent',
   description: 'Triages incoming requests and hands off to specialists',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   inputSchema: {
     request: z.string().describe('The incoming user request'),
   },
@@ -391,7 +391,7 @@ class TriageAgent extends AgentContext {}
 @Agent({
   name: 'billing_agent',
   description: 'Handles billing and payment inquiries',
-  llm: { adapter: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
   tools: [LookupInvoiceTool, ProcessRefundTool],
   swarm: {
     role: 'specialist',
@@ -413,7 +413,7 @@ const QuickSummarizer = agent({
   name: 'quick_summarizer',
   description: 'Summarizes text quickly',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -494,7 +494,7 @@ Protect agents with throttling controls:
   name: 'expensive_agent',
   description: 'An agent that performs expensive LLM operations',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -523,7 +523,7 @@ Agents can include their own providers and plugins for self-contained dependency
   name: 'database_agent',
   description: 'Agent that interacts with databases',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -548,7 +548,7 @@ Agents can include resources and prompts that are available within the agent's s
   name: 'docs_agent',
   description: 'Agent that manages documentation',
   llm: {
-    adapter: 'anthropic',
+    provider: 'anthropic',
     model: 'claude-sonnet-4-20250514',
     apiKey: { env: 'ANTHROPIC_API_KEY' },
   },
@@ -561,3 +561,46 @@ Agents can include resources and prompts that are available within the agent's s
 })
 class DocsAgent extends AgentContext {}
 ```
+
+## Common Patterns
+
+| Pattern                 | Correct                                                                       | Incorrect                                                      | Why                                                                             |
+| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| LLM config              | `llm: { provider: 'anthropic', model: '...', apiKey: { env: 'KEY' } }`        | `llm: { provider: 'anthropic', apiKey: 'sk-hardcoded' }`       | Environment variable references prevent leaking secrets in code                 |
+| Inner tools vs exported | `tools: [...]` for agent-private; `exports: { tools: [...] }` for MCP-visible | Putting all tools in `tools` and expecting clients to see them | Inner tools are private to the agent; only exported tools appear in MCP listing |
+| Custom execute          | Override `execute()` for multi-pass orchestration                             | Putting all logic in system instructions                       | Custom `execute()` gives structured control over completion calls and stages    |
+| Sub-agents              | Use `agents: [SubAgent]` for composition                                      | Calling another agent's `execute()` directly                   | The `agents` array enables proper lifecycle, scope isolation, and handoff       |
+| Swarm handoff           | Use `swarm.handoff` with `agent` name and `condition`                         | Manually routing between agents in `execute()`                 | Swarm config enables declarative, LLM-driven handoff between agents             |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Agent class extends `AgentContext` and has `@Agent` decorator with `name`, `description`, and `llm`
+- [ ] `inputSchema` is defined with Zod raw shape for input validation
+- [ ] Inner tools in `tools` array are valid `@Tool` classes
+- [ ] Agent is registered in `agents` array of `@App` or `@FrontMcp`
+- [ ] API key uses `{ env: 'VAR_NAME' }` pattern, not hardcoded strings
+
+### Runtime
+
+- [ ] Agent appears in MCP tool listing (agents surface as callable tools)
+- [ ] LLM adapter connects successfully to the configured provider
+- [ ] Inner tools are invoked correctly during the agent loop
+- [ ] `this.completion()` and `this.streamCompletion()` return valid responses
+- [ ] Swarm handoff transfers control to the correct specialist agent
+
+## Troubleshooting
+
+| Problem                             | Cause                                                 | Solution                                                                          |
+| ----------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Agent not appearing in tool listing | Not registered in `agents` array                      | Add agent class to `@App` or `@FrontMcp` `agents` array                           |
+| LLM authentication error            | API key not set or incorrect env variable             | Verify the environment variable name in `apiKey: { env: '...' }` is set           |
+| Inner tools not being called        | Tools not listed in `tools` array of `@Agent`         | Add tool classes to the `tools` field in the `@Agent` decorator                   |
+| Agent times out                     | No timeout or rate limit configured                   | Add `timeout: { executeMs: 120_000 }` and `rateLimit` to `@Agent` options         |
+| Swarm handoff fails                 | Target agent name does not match any registered agent | Ensure `handoff.agent` matches the `name` of a registered agent in the same scope |
+
+## Reference
+
+- [Agents Documentation](https://docs.agentfront.dev/frontmcp/servers/agents)
+- Related skills: `create-tool`, `create-provider`, `create-prompt`, `create-resource`