@frontmcp/skills 0.0.1 → 1.0.0-beta.11

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

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

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

@@ -1,38 +1,33 @@
 ---
 name: create-resource
-description: Create MCP resources and resource templates with URI-based access. Use when exposing data via URIs, creating resource templates, or serving dynamic content.
-tags: [resources, mcp, uri, templates, decorator]
-tools:
-  - name: create_resource
-    purpose: Scaffold a new resource or resource template class
-parameters:
-  - name: name
-    description: Resource name in kebab-case
-    type: string
-    required: true
-  - name: type
-    description: Whether to create a static resource or resource template
-    type: string
-    required: false
-examples:
-  - scenario: Create a static configuration resource
-    expected-outcome: Resource registered and readable via MCP at a fixed URI
-  - scenario: Create a resource template for user profiles
-    expected-outcome: Resource template with parameterized URI pattern
-priority: 10
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/resources
+description: Expose data to AI clients via URI-based static resources and parameterized templates
 ---
 
 # Creating MCP Resources
 
 Resources expose data to AI clients through URI-based access following the MCP protocol. FrontMCP supports two kinds: **static resources** with fixed URIs (`@Resource`) and **resource templates** with parameterized URI patterns (`@ResourceTemplate`).
 
-## When to Use @Resource vs @ResourceTemplate
+## When to Use This Skill
 
-Use `@Resource` when the data lives at a single, known URI (e.g., `config://app/settings`, `status://server`). Use `@ResourceTemplate` when you need a family of related resources identified by parameters in the URI (e.g., `users://{userId}/profile`, `repo://{owner}/{repo}/files/{path}`).
+### Must Use
+
+- Exposing data to AI clients through URI-based access following the MCP protocol
+- Serving dynamic or static content that clients read on demand (config, status, files)
+- Creating parameterized URI patterns for families of related data (user profiles, repo files)
+
+### Recommended
+
+- Providing binary assets (images, PDFs) to AI clients via base64 blob encoding
+- Centralizing read-only data sources that multiple tools or prompts reference
+- Replacing ad-hoc tool responses with structured, cacheable resource URIs
+
+### Skip When
+
+- The client needs to perform an action, not read data (see `create-tool`)
+- You are building a reusable conversation template (see `create-prompt`)
+- The data requires autonomous multi-step reasoning to produce (see `create-agent`)
+
+> **Decision:** Use this skill when you need to expose readable data at a URI -- choose `@Resource` for a fixed URI or `@ResourceTemplate` for parameterized URI patterns.
 
 ## Static Resources with @Resource
 
@@ -41,9 +36,11 @@ Use `@Resource` when the data lives at a single, known URI (e.g., `config://app/
 The `@Resource` decorator accepts:
 
 - `name` (required) -- unique resource name
+- `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
 - `uri` (required) -- static URI with a valid scheme per RFC 3986
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
+- `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
 ### Class-Based Pattern
 
@@ -148,9 +145,11 @@ Supported return shapes:
 The `@ResourceTemplate` decorator accepts:
 
 - `name` (required) -- unique resource template name
+- `title` (optional) -- human-readable display title for UIs (if omitted, `name` is used)
 - `uriTemplate` (required) -- URI pattern with `{paramName}` placeholders (RFC 6570 style)
 - `description` (optional) -- human-readable description
 - `mimeType` (optional) -- MIME type of the resource content
+- `icons` (optional) -- array of Icon objects for UI representation (per MCP spec)
 
 ### Class-Based Pattern
 
@@ -435,3 +434,126 @@ nx generate @frontmcp/nx:resource
 ```
 
 This creates the resource file, spec file, and updates barrel exports.
+
+## Resource Argument Autocompletion
+
+Resource templates with parameterized URIs can provide autocompletion for their arguments. This is useful when template parameters represent dynamic values that can be searched or enumerated, such as user IDs, product names, or project slugs.
+
+### When to Use
+
+- Template parameters reference entities that exist in a database or external service (user IDs, product names, etc.)
+- Clients benefit from discovering valid parameter values without prior knowledge
+- The parameter space is searchable or enumerable given a partial input string
+
+### Types
+
+The autocompletion API uses two types from `@frontmcp/sdk`:
+
+```typescript
+interface ResourceCompletionResult {
+  values: string[];
+  total?: number;
+  hasMore?: boolean;
+}
+
+type ResourceArgumentCompleter = (partial: string) => Promise<ResourceCompletionResult> | ResourceCompletionResult;
+```
+
+- `values` -- the list of matching completions for the partial input
+- `total` -- optional total number of matches (useful when `values` is a truncated subset)
+- `hasMore` -- optional flag indicating additional matches exist beyond what was returned
+
+### How to Implement
+
+Override the `getArgumentCompleter(argName)` method in your `ResourceContext` subclass. Return a completer function for argument names you support, or `null` for unknown arguments.
+
+```typescript
+getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
+  if (argName === 'myParam') {
+    return async (partial) => {
+      // Search or filter based on partial input
+      const matches = await findMatches(partial);
+      return { values: matches, total: matches.length };
+    };
+  }
+  return null;
+}
+```
+
+### Complete Example
+
+A user profile template resource that autocompletes user IDs by searching a user service:
+
+```typescript
+@ResourceTemplate({
+  name: 'user-profile',
+  description: 'User profile by ID',
+  uriTemplate: 'users://{userId}/profile',
+  mimeType: 'application/json',
+})
+class UserProfileResource extends ResourceContext<{ userId: string }> {
+  async execute(uri: string, params: { userId: string }) {
+    const user = await this.get(UserService).findById(params.userId);
+    return { id: user.id, name: user.name, email: user.email };
+  }
+
+  getArgumentCompleter(argName: string): ResourceArgumentCompleter | null {
+    if (argName === 'userId') {
+      return async (partial) => {
+        const users = await this.get(UserService).search(partial);
+        return { values: users.map((u) => u.id), total: users.length };
+      };
+    }
+    return null;
+  }
+}
+```
+
+When a client requests completions for the `userId` parameter with a partial string like `"al"`, the completer queries the user service and returns matching IDs.
+
+## Common Patterns
+
+| Pattern                | Correct                                                                  | Incorrect                                                               | Why                                                                              |
+| ---------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| URI scheme             | `uri: 'config://app/settings'` (valid scheme)                            | `uri: 'app-settings'` (no scheme)                                       | URIs are validated per RFC 3986; scheme-less URIs are rejected at registration   |
+| Resource vs template   | `@Resource` for fixed URIs, `@ResourceTemplate` for `{param}` URIs       | Using `@Resource` with `{param}` placeholders                           | Framework selects matching strategy based on decorator type                      |
+| Return shape           | Return full `ReadResourceResult` or let FrontMCP normalize plain objects | Manually wrapping every return in `{ contents: [...] }` when not needed | FrontMCP auto-wraps strings, objects, and arrays into valid `ReadResourceResult` |
+| Template params typing | `ResourceContext<{ userId: string }>` with typed `params`                | `ResourceContext` with untyped `params: Record<string, string>`         | Generic parameter enables compile-time checking of URI parameters                |
+| Binary content         | Use `blob` field with base64 encoding for binary data                    | Returning raw `Buffer` in `text` field                                  | MCP protocol expects base64 in `blob`; `text` is for string content only         |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] Resource class extends `ResourceContext` and implements `execute(uri, params)`
+- [ ] `@Resource` has `name` and `uri` with a valid scheme, or `@ResourceTemplate` has `name` and `uriTemplate`
+- [ ] Resource is registered in `resources` array of `@App` or `@FrontMcp`
+- [ ] `mimeType` is set when the content type is not plain text
+
+### Runtime
+
+- [ ] Resource appears in `resources/list` MCP response
+- [ ] Reading the resource URI returns the expected `ReadResourceResult`
+- [ ] Template parameters are extracted correctly from the URI
+- [ ] Binary resources return valid base64 in the `blob` field
+- [ ] DI dependencies resolve correctly via `this.get()`
+
+### Autocompletion
+
+- [ ] Template resources with dynamic params implement `getArgumentCompleter()`
+- [ ] Completer returns `{ values, total?, hasMore? }` matching the partial input
+
+## Troubleshooting
+
+| Problem                                          | Cause                                            | Solution                                                                           |
+| ------------------------------------------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Resource not appearing in `resources/list`       | Not registered in `resources` array              | Add resource class to `@App` or `@FrontMcp` `resources` array                      |
+| URI validation error at startup                  | Missing or invalid URI scheme                    | Ensure URI has a scheme like `config://`, `https://`, or `custom://`               |
+| Template parameters are empty                    | Using `@Resource` instead of `@ResourceTemplate` | Switch to `@ResourceTemplate` with `uriTemplate` containing `{param}` placeholders |
+| Binary content is garbled                        | Returning raw buffer in `text` field             | Use `blob: buffer.toString('base64')` instead of `text` for binary data            |
+| `this.get(TOKEN)` throws DependencyNotFoundError | Provider not registered in scope                 | Register provider in `providers` array of `@App` or `@FrontMcp`                    |
+
+## Reference
+
+- [Resources Documentation](https://docs.agentfront.dev/frontmcp/servers/resources)
+- Related skills: `create-tool`, `create-prompt`, `create-provider`, `create-agent`

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

@@ -1,31 +1,33 @@
 ---
 name: create-skill-with-tools
-description: Create skills that reference and orchestrate MCP tools for multi-step workflows. Use when building skills with tool references, SKILL.md directories, or workflow instructions.
-tags: [skill, tools, workflow, instructions]
-parameters:
-  - name: name
-    description: Skill name in kebab-case
-    type: string
-    required: true
-examples:
-  - scenario: Create a deploy skill that uses build and test tools
-    expected-outcome: Skill guides AI through build, test, deploy workflow
-  - scenario: Create a skill from a SKILL.md file directory
-    expected-outcome: Skill loaded with instructions, scripts, references, assets
-priority: 8
-visibility: both
-license: Apache-2.0
-metadata:
-  docs: https://docs.agentfront.dev/frontmcp/servers/skills
+description: Create skills that combine structured instructions with MCP tool references for orchestration
 ---
 
 # Creating a Skill with Tools
 
 Skills are knowledge and workflow guides that help LLMs accomplish multi-step tasks using available MCP tools. Unlike tools (which execute actions directly) or agents (which run autonomous LLM loops), skills provide structured instructions, tool references, and context that the AI client uses to orchestrate tool calls on its own.
 
-## When to Use @Skill
+## When to Use This Skill
+
+### Must Use
+
+- Teaching an AI client how to accomplish a complex task by combining multiple tools in a defined sequence
+- Building directory-based skills with `SKILL.md`, scripts, references, and assets loaded via `skillDir()`
+- Defining tool-orchestration instructions with explicit tool references, parameters, and examples
+
+### Recommended
+
+- Creating reusable workflow guides that can be discovered via HTTP (`/llm.txt`, `/skills`) or MCP protocol
+- Wrapping existing tools into a higher-level procedure with step-by-step instructions and validation modes
+- Providing AI clients with structured playbooks for incident response, deployment, or data-processing flows
+
+### Skip When
 
-Use `@Skill` when you want to teach an AI client HOW to accomplish a complex task by combining multiple tools in sequence. A skill does not execute anything itself -- it provides the instructions, tool references, and examples that guide the AI through a workflow.
+- You need a single executable action with direct input/output (see `create-tool`)
+- You need an autonomous LLM loop that reasons across multiple steps on its own (see `create-agent`)
+- You are building a conversational template or system prompt without tool references (see `create-prompt`)
+
+> **Decision:** Use this skill when you need to guide an AI client through a multi-tool workflow using structured instructions and tool references, without executing anything directly.
 
 | Aspect     | @Skill                   | @Tool                | @Agent               |
 | ---------- | ------------------------ | -------------------- | -------------------- |
@@ -215,7 +217,7 @@ class RemoteWorkflowSkill extends SkillContext {}
 
 Use `skillDir()` to load a skill from a directory structure. The directory is expected to contain a `SKILL.md` file with frontmatter and instructions, plus optional subdirectories for scripts, references, and assets.
 
-```
+```text
 skills/
   deploy-service/
     SKILL.md           # Instructions with YAML frontmatter
@@ -344,6 +346,44 @@ Use `hideFromDiscovery: true` to register a skill that is not listed in discover
 class AdminMaintenanceSkill extends SkillContext {}
 ```
 
+## Agent Skills Spec Fields
+
+Skills support additional metadata fields from the Anthropic Agent Skills specification:
+
+```typescript
+@Skill({
+  name: 'deploy-to-prod',
+  description: 'Production deployment workflow',
+  instructions: { file: './deploy-prod.md' },
+  tools: [BuildTool, DeployTool, HealthCheckTool],
+  priority: 10, // Higher = earlier in search results
+  license: 'MIT', // License identifier
+  compatibility: 'Node.js 24+, Docker', // Environment requirements (max 500 chars)
+  allowedTools: 'Read Edit Bash(git status)', // Pre-approved tools (space-delimited)
+  specMetadata: {
+    // Arbitrary key-value metadata
+    author: 'platform-team',
+    version: '2.0.0',
+  },
+  resources: {
+    // Bundled resource directories
+    scripts: './scripts', // Helper scripts
+    references: './references', // Reference documents
+    assets: './assets', // Static assets
+  },
+})
+class DeployToProdSkill extends SkillContext {}
+```
+
+| Field           | Description                                                      |
+| --------------- | ---------------------------------------------------------------- |
+| `priority`      | Search ranking weight; higher = earlier (default: `0`)           |
+| `license`       | License identifier (e.g., `'MIT'`, `'Apache-2.0'`)               |
+| `compatibility` | Environment requirements (max 500 chars)                         |
+| `allowedTools`  | Space-delimited pre-approved tool names for the skill            |
+| `specMetadata`  | Arbitrary `Record<string, string>` map (Agent Skills `metadata`) |
+| `resources`     | Bundled dirs: `{ scripts?, references?, assets? }` paths         |
+
 ## Function-Style Builder
 
 For skills that do not need a class, use the `skill()` function builder:
@@ -577,3 +617,117 @@ class AuditApp {}
 })
 class AuditServer {}
 ```
+
+## CodeCall Compatibility
+
+When the `CodeCallPlugin` is active in `codecall_only` mode, all tools registered on the server are hidden from `list_tools`. The AI client only sees the three CodeCall meta-tools (`codecall:search`, `codecall:describe`, `codecall:execute`). This means skill instructions that reference tool names directly (e.g., "Use the `build_project` tool") become misleading -- the AI cannot call those tools because they do not appear in the tool listing.
+
+### When This Matters
+
+This is only relevant when the server initializes CodeCall in `codecall_only` mode:
+
+```typescript
+CodeCallPlugin.init({ mode: 'codecall_only' });
+```
+
+With `codecall_opt_in` or `metadata_driven` modes, tools remain visible in `list_tools` alongside the CodeCall meta-tools. In those modes, standard tool-referencing instructions continue to work without changes.
+
+### Writing Dual-Mode Instructions
+
+Write skill instructions that work regardless of whether CodeCall is active. Instead of referencing tool names as direct calls, instruct the AI to use the search-describe-execute pattern:
+
+```markdown
+## Step 1: Find Available Tools
+
+Search for tools related to your task using codecall:search.
+Query: ["build project", "run tests", "deploy"]
+
+## Step 2: Describe Tool Interfaces
+
+Once you find matching tools, use codecall:describe to understand their input schemas.
+
+## Step 3: Execute
+
+Use codecall:execute with an AgentScript that calls the tools:
+const build = await callTool('build_project', { target: 'production' });
+const tests = await callTool('run_tests', { suite: 'e2e' });
+```
+
+### Supporting Both Direct and CodeCall Workflows
+
+If you want the skill to work with and without CodeCall, list the tool names in the `tools` array (so they are associated with the skill in metadata) AND include instructions for both direct calls and the CodeCall workflow. This way:
+
+- In standard mode, the AI sees the tools in `list_tools` and can call them directly using the tool names from the `tools` array.
+- In `codecall_only` mode, the AI follows the search-describe-execute instructions to discover and invoke the same tools through CodeCall.
+
+```typescript
+@Skill({
+  name: 'deploy-service',
+  description: 'Deploy a service through the pipeline',
+  instructions: `# Deploy Service
+
+## Finding the Tools
+If tools are not directly visible, search for them:
+Use codecall:search with query ["build project", "run tests", "deploy to environment"].
+Then use codecall:describe on each result to confirm the input schema.
+
+## Step 1: Build
+Call build_project with the service name and target environment.
+If using CodeCall: codecall:execute with callTool('build_project', { ... }).
+
+## Step 2: Test
+Call run_tests with the test suite name.
+If using CodeCall: codecall:execute with callTool('run_tests', { ... }).`,
+  tools: [BuildProjectTool, RunTestsTool, DeployToEnvTool],
+})
+class DeployServiceSkill extends SkillContext {}
+```
+
+## Common Patterns
+
+| Pattern                | Correct                                                                               | Incorrect                                                      | Why                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Tool references        | `tools: [BuildTool, 'run_tests', { name: 'deploy', purpose: '...', required: true }]` | `tools: [{ class: BuildTool }]` (object with `class` key)      | The `tools` array accepts class refs, strings, or `{ name, purpose, required }` objects only |
+| Tool validation        | `toolValidation: 'strict'` for production skills                                      | Omitting `toolValidation` for critical workflows               | Default is `'warn'`; production skills should fail fast on missing tools with `'strict'`     |
+| Instruction source     | `instructions: { file: './skills/deploy.md' }` for long content                       | Inlining hundreds of lines in the decorator string             | File-based instructions keep decorator metadata readable and instructions maintainable       |
+| Skill visibility       | `visibility: 'both'` (default) for public skills                                      | Setting `visibility: 'mcp'` when HTTP discovery is also needed | Skills with `'mcp'` visibility are hidden from `/llm.txt` and `/skills` HTTP endpoints       |
+| Parameter types        | `parameters: [{ name: 'env', type: 'string', required: true }]`                       | `parameters: { env: 'string' }` (plain object shape)           | Parameters must be an array of `{ name, description, type, required?, default? }` objects    |
+| CodeCall compatibility | List tools AND include codecall:search/execute instructions                           | Only listing tools by name                                     | When CodeCall hides tools, AI can't find them without search instructions                    |
+
+## Verification Checklist
+
+### Configuration
+
+- [ ] `@Skill` decorator has `name` and `description`
+- [ ] `instructions` are provided via inline string, `{ file }`, or `{ url }`
+- [ ] All tool references in `tools` array resolve to registered tools (when `toolValidation: 'strict'`)
+- [ ] Skill is registered in `skills` array of `@App` or `@FrontMcp`
+
+### Runtime
+
+- [ ] Skill appears in MCP skill listing (`skills/list`) when `visibility` includes `'mcp'`
+- [ ] Skill appears at `/llm.txt` and `/skills` HTTP endpoints when `visibility` includes `'http'`
+- [ ] `build()` returns complete `SkillContent` with instructions and tool references
+- [ ] `getToolRefs()` returns the correct list of resolved tool references
+- [ ] Hidden skills (`hideFromDiscovery: true`) are invocable but not listed in discovery
+
+### Directory-Based Skills
+
+- [ ] `SKILL.md` file exists at the root of the skill directory with valid YAML frontmatter
+- [ ] `skillDir()` correctly loads instructions, scripts, references, and assets
+- [ ] Frontmatter `tools` entries match registered tool names
+
+## Troubleshooting
+
+| Problem                                      | Cause                                                       | Solution                                                                               |
+| -------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Skill not appearing in `/llm.txt`            | `visibility` is set to `'mcp'`                              | Change to `'both'` or `'http'` to include HTTP discovery                               |
+| `toolValidation: 'strict'` throws at startup | A referenced tool is not registered in the scope            | Register all referenced tools in the `tools` array of `@App` or `@FrontMcp`            |
+| `skillDir()` fails to load                   | `SKILL.md` file missing or frontmatter is invalid YAML      | Ensure the directory contains a `SKILL.md` with valid `---` delimited YAML frontmatter |
+| Instructions are empty at runtime            | `{ file: './path.md' }` path is relative to wrong directory | Use a path relative to the skill file's location, not the project root                 |
+| Parameters not visible to AI client          | `parameters` defined as a plain object instead of an array  | Use array format: `[{ name, description, type, required }]`                            |
+
+## Reference
+
+- [Skills Documentation](https://docs.agentfront.dev/frontmcp/servers/skills)
+- Related skills: `create-skill`, `create-tool`, `create-agent`, `create-prompt`