@Skill

Checked against FrontMCP 1.12.2 on

@Skill declares a skill: a procedure written down for the client's model, with the tools it uses, its parameters and examples. FrontMCP serves it as skill:// resources, and answers FrontMCP's own skills/search, skills/list and skills/load requests. A skill adds no tool: the client's model reads the steps and does the work itself, with your tools. A skill written as a folder with a SKILL.md loads with skillDir(). To run a procedure on your server's model instead, write an agent.

@Skill(options)
class MySkill {}

Reference

@Skill(options)

Apply @Skill to a class, and list the class in an app's skills array. The class holds no code: FrontMCP only reads the options.

triage-ticket.skill.ts
import { Skill } from "@frontmcp/sdk";

@Skill({
  name: "triage-ticket",
  description: "Decide a new support ticket's priority and who handles it.",
  instructions: `1. Read the ticket with get_ticket.
2. Search for tickets from the same customer with search_tickets. If one is open about the same problem, say so.
3. Set the priority with set_priority: high if the customer can't work, normal otherwise.
4. Assign it with assign_ticket: billing questions to the billing team, everything else to support.`,
  tools: [
    "get_ticket",
    "search_tickets",
    { name: "set_priority", purpose: "Record the priority", required: true },
    "assign_ticket",
  ],
  parameters: [{ name: "ticketId", description: "The ticket to triage, like T-1", required: true }],
  examples: [{ scenario: "Acme can't log in", parameters: { ticketId: "T-1" }, expectedOutcome: "T-1 is high priority, assigned to support" }],
  tags: ["support"],
})
export class TriageTicket {}
help-desk.app.ts
import { App } from "@frontmcp/sdk";
import { AssignTicket, GetTicket, SearchTickets, SetPriority } from "./ticket.tools";
import { TriageTicket } from "./triage-ticket.skill";

@App({
  id: "help-desk",
  name: "Help Desk",
  tools: [GetTicket, SearchTickets, SetPriority, AssignTicket],
  skills: [TriageTicket],
})
export class HelpDeskApp {}

See more examples below.

Options

Required:

OptionTypeDescription
namestringThe skill's name, in kebab-case: lowercase letters, digits and hyphens. Any other name stops the server from starting. The resource is skill://<name>/SKILL.md.
descriptionstringWhat the procedure is for. Clients show it in search results and in skill://index.json, and the client's model decides from it whether to load the skill.
instructionsstring | { file: string } | { url: string }The procedure: inline, or read from a file or a URL. See instructions.

Optional:

OptionTypeDefaultDescription
tools(string | ToolClass | { name, purpose?, required? } | { tool, purpose?, required? })[][]The tools the procedure uses, by name or by class. They're listed by name in SKILL.md and in skills/load, each marked available if it's in the server's tools/list. A tool that availableWhen.surface keeps from the caller counts as missing too (since 1.8.5). purpose says what the tool is for in this procedure. Tool classes work since 1.9: before, they stopped the server from starting.
parameters{ name, description?, required?, type?, default? }[][]What the procedure needs to know before it starts. type is "string" (the default), "number", "boolean", "object" or "array".
examples{ scenario, parameters?, expectedOutcome? }[][]When to use the skill, and what should happen.
tagsstring[][]For clients to filter skills/search and skills/list by. Not in SKILL.md.
idstringnameReplaces name as the skill's id in skills/search, skills/list and skills/load. The resource is listed as skill://<name>/SKILL.md, and since 1.8.5 skill://<id>/SKILL.md reads it too. An id that is another skill's name stops the server from starting, with InvalidSkillError.
prioritynumber0skills/list can sort by it. It doesn't change the order of skills/search results.
hideFromDiscoverybooleanfalseLeaves the skill out of the resources, skill://index.json, skills/search and skills/list. skills/load still loads it by id. See Hiding a skill.
visibility"mcp" | "http" | "both""both""http" leaves the skill out of the resources, the index and skills/search, for the HTTP endpoints only. skills/list leaves it out too; skills/load still loads it by id.
toolValidation"strict" | "warn" | "ignore""warn"What to do when a tool in tools doesn't exist. "warn" logs a warning, and the skill loads with the tool in missingTools. "strict" stops the server from starting, with a SkillValidationError (since 1.9; before, it started anyway).
skillPathstring[][name]A longer resource path, ending with name: ["billing", "refunds"] serves skill://billing/refunds/SKILL.md.
license, compatibility, specMetadata, allowedToolsstring, string, Record<string, string>, stringnoneFields from the Agent Skills format. They're written into SKILL.md's frontmatter as license, compatibility, metadata and allowed-tools. FrontMCP doesn't act on allowedTools: it's there for the client to read.
resources{ scripts?, references?, assets?, examples? }noneFolders of files that come with the skill, each an absolute path or one relative to the file that declares the skill. Clients read a file in them at skill://<name>/<folder>/<file>, like skill://triage-ticket/references/priorities.md, and the files in references are listed in a table under the instructions. skillDir() fills it in from a skill's folder. They're read from disk, so the Playground can't show them: see Loading a skill from a SKILL.md folder.
availableWhenEntryAvailabilitynoneOnly serve the skill on some platforms or runtimes, or to some callers: a surface without "mcp" keeps it from MCP clients. Where it doesn't match, the skill isn't served at all: it's left out of the resources, skill://index.json, skills/list, skills/search, skills/load and the HTTP endpoints, and its SKILL.md can't be read. See A skill isn't listed, and can't be loaded and Environment awareness.
category, ratingstring, numbernoneFor the HTTP endpoints. Not in the MCP responses.
referencedOperations, alwaysLoadnoneFor FrontMCP's code-execution plugin. This page doesn't cover them.

instructions

SourceExampleWhen it's read
Inlineinstructions: "1. Read the ticket…"At once.
A fileinstructions: { file: "./triage-ticket.md" }When the server starts, like a URL, then kept. The path is relative to the file that declares the skill.
A URLinstructions: { url: "https://docs.example.com/triage.md" }When the server starts, with fetch, then kept.

A file or URL that can't be read doesn't stop the server. The skill is left out of skills/list, and each request that needs it tries again and fails, as in Troubleshooting. A frontmatter block at the top of a fetched file is kept as it is, so SKILL.md ends up with two. The Playground has no files and no network, so its examples use inline instructions.

What a skill adds to the server

WhatKindDescription
skill://index.jsonresourceThe discovery index, in the Agent Skills discovery format: each skill's name, description and url.
skill://<name>/SKILL.mdresource, one per skillThe skill as a Markdown file: YAML frontmatter, then the instructions. See SKILL.md.
skill://{+skillPath}/SKILL.md, skill://{+skillPath}/{+filePath}resource templatesRead any skill's SKILL.md, or a file in its directory.
skills/search, skills/list, skills/loadJSON-RPC requestsFrontMCP's own requests, not part of MCP. See below.
io.modelcontextprotocol/skillscapabilityIn capabilities.extensions of server/discover, so clients know the server has skills.
A pointer to the skillsinstructionsAdded to the server's instructions in server/discover and initialize, after the server's own: the number of skills the caller can see and where to read them, or, while a plugin's skills haven't loaded, that they haven't. See Serving a skill and SkillCatalogSourceToken.

A skill adds no tools: tools/list is the same with or without it. Clients that support skills read the resources; the rest can still list and read them as resources, and their model finds the skills in the server's instructions.

SKILL.md

---
name: triage-ticket
description: Decide a new support ticket's priority and who handles it.
tools:
  - get_ticket
  - name: set_priority
    purpose: Record the priority
    required: true
parameters:
  - name: ticketId
    description: The ticket to triage, like T-1
    required: true
    type: string
examples:
  - scenario: Acme can't log in
    parameters:
      ticketId: T-1
    expectedOutcome: T-1 is high priority, assigned to support
---

1. Read the ticket with get_ticket.
…

The frontmatter has name, description, tools, parameters, examples and the Agent Skills fields, as you wrote them. It doesn't have tags or priority.

skills/search

Finds skills by the words of a query. A skill is matched by its description, which counts most, its tags, its name, its tools and their purpose, its parameters and examples, the actions of a skill a plugin registers, and up to 48 distinct words of its instructions. Stop words, like the, of and and, count in neither the query nor the skills, and words count in any script, not only in Latin letters.

ParameterTypeDescription
querystringRequired. Words to look for.
tagsstring[]Only skills with one of these tags.
toolsstring[]Only skills that use these tools.
requireAllToolsbooleanLeave out skills that use a tool the server doesn't have.
limitnumberAt most this many skills, from 1 to 50. Default 10.

Returns { skills, total, hasMore, guidance }. Each skill has id, name, description, score (from 0 to 1), tags, tools (each { name, available }), source: "local", and, for a skill a plugin registered from a bundle, bundleVersion. guidance is a sentence for the model: Found 1 matching skill(s). Use skills/load with skill IDs to load full content., or, with no match, No matching skills found. Try different search terms or list all skills with skills/list. Skills hidden with hideFromDiscovery or visibility: "http" aren't searched. With skillsConfig.decision, a model ranks the results, and score is its probability.

Changed in 1.11.1: before, the words of a skill's instructions and a plugin skill's actions weren't searched, stop words counted, so the of and found skills, and the index kept only the letters A to Z, digits and _, so words in other scripts were found only by a keyword fallback, which scored each skill by the share of the query's words it contained.

skills/list

Lists skills, sorted by name.

ParameterTypeDescription
tagsstring[]Only skills with one of these tags.
sortBy"name" | "priority" | "createdAt"The order.
sortOrder"asc" | "desc"
offset, limitnumberA page of the list.
includeHiddenbooleanAlso list skills with hideFromDiscovery.

Returns { skills, total, hasMore }, each skill with id, name, description, tags and priority, and, for a skill a plugin registered from a bundle, bundleVersion.

skills/load

Loads skills by id or name, with everything the model needs to follow them.

ParameterTypeDescription
skillIdsstring[]Required, 1–100 ids. The skills to load. Duplicate ids, including an id and its name, load the skill once.
activateSessionbooleanDefault false. Activate the loaded skills for the verified MCP session. A request without one returns session: { activated: false }.
policyMode"strict" | "approval" | "permissive"Default "permissive". Strict refuses tools outside the active skills' combined allowlist; approval refuses them pending approval; permissive runs them and logs a warning.
format"full" | "markdown" | "instructions-only"What each skill is sent as. "full", the default, sends the fields below, each available tool's inputSchema in tools, and formattedContent, which holds them all again. "markdown" sends formattedContent without instructions and parameters, and tools without schemas, so each part is sent once. "instructions-only" is "full" without the tool schemas, in tools and in formattedContent.

Returns { skills, summary, nextSteps }. Each skill has id, name, description, instructions, tools (each { name, purpose?, available, inputSchema? }), parameters, availableTools, missingTools, isComplete, and formattedContent: the whole skill as one Markdown text for the model, with a [✓] or [✗] for each tool and its input schema. summary has totalSkills, totalTools, allToolsAvailable and combinedWarnings, which names missing tools and ids that weren't found. An id that isn't found isn't an error: it's left out, with a warning, unless a plugin's skills haven't loaded yet. nextSteps is Loaded 1 skill(s). Follow the instructions to complete the task., or, with "markdown", … Follow each formattedContent to complete the task.

Changed in 1.11.1: "markdown" is new, and "instructions-only" leaves the tool schemas out of formattedContent too; before, it left them out of tools only.

skills/load accepts at most 100 ids and reports tools withheld by authorities or publicAccess as missing. A custom SkillSessionManager with requireExplicitActivation: true refuses calls without an active skill. An activation policy with strictAllowlist: true refuses tools outside its allowlist even in permissive mode.

Skill sessions

With activateSession: true, each loaded skill reports session: { activated: true, sessionId, policyMode, allowedTools } when the request has a verified MCP session. Later tool calls in that session follow its skill policy. Ending the MCP session forgets the activation. Without an active skill, ordinary tool calls remain allowed unless a custom session manager sets requireExplicitActivation: true. A ToolNotAllowedError with reason no_active_skill tells the client: Activate a skill first: send a skills/load request with activateSession: true. The store holds at most 10,000 activated sessions; a further activation fails with SKILL_SESSION_LIMIT.

Changed in 1.11.3: before, the option did not activate the caller's MCP session. MCP 2026-07-28 and the stateless fetch handler have no verified session and report activated: false. They can still read and follow a skill:

const loaded = await mcp.raw.request({
  jsonrpc: "2.0", id: 1, method: "skills/load",
  params: { skillIds: ["triage-ticket"], activateSession: true, policyMode: "strict" },
});

Server options: skillsConfig

The server's skillsConfig option controls how skills are served beyond MCP. You don't need it to use skills.

OptionTypeDefaultDescription
enabledbooleanfalseAdds HTTP endpoints for skills: /llm.txt, /llm_full.txt and /skills. See Serving skills over HTTP.
externalProviderExternalSkillProviderBasenoneInitializes and installs an external provider at startup. It must implement the full provider interface. See External skill storage.
mcpResourcesbooleantruefalse removes every skill:// resource and template. skills/search, skills/list and skills/load still work.
injectInstructions"compact" | "append" | "prepend" | "replace" | "off""compact"How skills join the server instructions. See Instruction modes.
resourceAnnotations"no-priority" | "full" | "off""no-priority"Annotations on each SKILL.md in resources/list: assistant audience and, for file-backed skills, lastModified. "full" also sends priority: 0.8; "off" omits annotations.
sep2640InInstructionsbooleanfalseAdds skill URI hints, even with injectInstructions: "off". Ignored with mcpResources: false.
failOnInvalidSkillsbooleantruefalse lets the server start when a skill with toolValidation: "strict" names a tool it doesn't have: the server logs an error instead, and serves the skill with the tool in missingTools. See Troubleshooting. (New in 1.9.2: before, it couldn't be set.)
decisionSkillDecisionOptionsnoneRanks skills/search with a decision model: a model that answers a choice among options with a probability for each. See skillsConfig.decision. New in 1.11.1.

skillsConfig also has options for the HTTP endpoints (prefix, auth, apiKeys, jwt, llmTxt, llmFullTxt, api, cache), and scoring and audit, which this page doesn't cover. Skills over HTTP covers who can reach the endpoints.

With the default skillsConfig.auth, "inherit", the endpoints use the server's auth: a server that requires a key or a token for MCP requires the same one for /skills, /llm.txt and /llm_full.txt, and answers 401 without it. A server without auth, or in public mode, serves them to anyone. A skill with authorities is left out for a caller its rule refuses, and /skills/<id> answers 404 for it. See Serving skills over HTTP.

Changed in 1.8.3: before, "inherit" let anyone read the endpoints, even on a server that required a key for MCP, and /llm.txt and /llm_full.txt listed skills with authorities, instructions and all. To keep the endpoints open on a server with auth, set skillsConfig.auth: "public".

Instruction modes

injectInstructionsWhat the client receives
"compact"Your instructions and channel hints, then one line with the number of skills the caller may see and a pointer to skill://index.json. With mcpResources: false, it points to skills/search and skills/load instead. No line when the caller sees no skills. A read-only externalProvider gives This server has skills: …, without a count.
"append"Your instructions, channel hints, then the full catalog: Available skills, followed by each skill's name and description.
"prepend"The full catalog, channel hints, then your instructions.
"replace"Your instructions alone, without the catalog or channel hints. Empty instructions fall back to "append".
"off"Your instructions and channel hints, without the catalog. URI hints from sep2640InInstructions still apply.

Changed in 1.10.16: before, injectInstructions defaulted to "append", and SKILL.md resources carried numeric priority: 0.8. Set injectInstructions: "append" and resourceAnnotations: "full" to restore those defaults. The compact line avoids repeating a full catalog in clients that copy server instructions into tool descriptions; the catalog modes are capped at 16,000 characters.

The exported composeInitializeInstructions() and composeCallerInstructions() helpers also use "compact" when no policy is set.

skillsConfig.decision

skillsConfig: { decision: { decider: decisionsApiDecider({ apiKey: process.env.OPENAI_API_KEY! }) } }

Ranks skills/search with a decision model, without embeddings. The search index picks the candidates, the model gives each a probability, and the results are ranked by it, each with its probability as score. In a catalog of no more than maxCandidates skills, every skill is a candidate, so a query that shares no word with a skill can still find it. A decision that fails, takes longer than timeoutMs, or gives a probability outside 0 to 1 leaves the results ranked by the index, and logs a warning. New in 1.11.1.

OptionTypeDefaultDescription
deciderSkillDecidernoneRequired. The model: async ({ query, notQuery, candidates, signal }) => [{ id, probability }]. Each candidate is { id, name, description, tags? }; notQuery is an array of what the caller doesn't want, empty for skills/search; signal aborts after timeoutMs. Return a probability from 0 to 1 for each candidate the model judged: one left out counts as 0.
maxCandidatesnumber50The most skills the model chooses among, from 1 to 254: the index's best matches, or every skill when there are no more.
minProbabilitynumber0.1Leaves out results with a lower probability.
timeoutMsnumber5000How long a decision may take, in milliseconds.
cachefalse | { ttlMs?, maxEntries? }{ ttlMs: 600000, maxEntries: 500 }Keeps decisions in memory, keyed by the query, notQuery and the candidates, so a repeated search makes no call. false turns it off.

decisionsApiDecider(options) returns a SkillDecider for the Decisions API: it sends POST <baseUrl>/decisions with one choice question, whose choices are the candidates and __none__, for "none of these skills fits".

OptionTypeDefaultDescription
apiKeystringnoneRequired. Sent as Authorization: Bearer <apiKey>.
baseUrlstring"https://api.openai.com/v1"Another service with the same contract works too, like "https://api.llmgateway.io/v1" with model: "jev-1.13.0".
modelstring"gpt-6-luna"
fetchtypeof fetchthe global fetch

An answer other than 2xx, or one without a choice answer, is a failed decision. The Playground can't reach a model, so Ranking search with a decision model uses a decider of its own.

skill(options)

The function form takes the same options and returns a skill to list in skills, like a class:

import { skill } from "@frontmcp/sdk";

export const refundPolicy = skill({
  name: "refund-policy",
  description: "How to answer a customer who asks for a refund.",
  instructions: "Refunds within 30 days of the charge are automatic. After 30 days, assign the ticket to billing.",
});

Caveats

  • tools takes tool names or tool classes. A class that isn't a tool stops the server from starting.
  • A tool is available only if it's in the server's tools/list. A tool that only an agent has counts as missing.
  • A skill is instructions, not code. Nothing makes the client's model follow them, or stops it calling tools the skill doesn't list.
  • To serve a REST API as skills, generated from its OpenAPI description, see Skilled OpenAPI.
  • The class doesn't need to extend anything. Extend SkillContext to override loadInstructions() or build(), which FrontMCP calls once, when the server starts: see Building a skill in code.
  • To add or remove a skill while the server runs, use this.scope.skills.registerSkillContent(): see Adding a skill at runtime.

skillDir(dir)

const triage = await skillDir("/srv/help-desk/skills/triage-ticket");

Reads a skill written as a folder in the Agent Skills format: a SKILL.md, with YAML frontmatter and then the procedure, and any of the folders references/, examples/, scripts/ and assets/. It returns a skill to list in an app's skills, like a class. loadSkillDirectory(dir) is the same function.

ParameterTypeDescription
dirstringAn absolute path, or a relative path resolved against the calling file, then the working directory. Changed in 1.9.5: before, relative paths were resolved from the filesystem root.
loggerFrontMcpLoggerOptional. A logger for the name warning, which otherwise goes to the console.

It returns a promise of the skill, a record whose metadata holds the options read from SKILL.md. Each folder it finds becomes an entry of resources.

How SKILL.md maps to options

In SKILL.mdBecomes
The Markdown after the frontmatterinstructions. Required: a SKILL.md with nothing after its frontmatter is refused.
name, descriptionThe options of the same name. Required.
id, license, compatibility, tags, tools, parameters, examples, priority, skillPath, visibility, category, ratingThe options of the same name.
allowed-toolsallowedTools.
metadataspecMetadata. A value that isn't a string is kept as JSON text: { max: 5 } becomes the string {"max":5}.
hide-from-discovery, tool-validation, available-when, and an example's expected-outcomehideFromDiscovery, toolValidation, availableWhen and expectedOutcome. The camelCase keys work too.
Any other key, like user-invocable: trueAdded to specMetadata, as a string, so the served SKILL.md has it under metadata.

What clients read

In the folderClients read it atAs
SKILL.mdskill://<name>/SKILL.md, listed in resources/listRebuilt from the options, like a declared skill's: the frontmatter of SKILL.md, without tags, then the instructions, then a ## References table with the name and description of each file in references/. skills/load returns the same instructions and table.
references/priorities.mdskill://<name>/references/priorities.mdText, without its frontmatter.
examples/acme-login.mdskill://<name>/examples/acme-login.mdText, without its frontmatter.
scripts/check-sla.shskill://<name>/scripts/check-sla.shText, as written, typed application/x-sh.
assets/teams.csvskill://<name>/assets/teams.csvA blob, base64, typed application/octet-stream.

Only SKILL.md is in resources/list. The other files are read through the skill://{+skillPath}/{+filePath} template: a client finds the references in the table, and the rest where the instructions name them. A file that isn't there, or a path with .., fails with Resource not found: skill://….

scanSkillResources(dir) returns what skillDir() looks for, without reading SKILL.md: { resources, hasSkillMd }, with the path of each of the four folders that exists. It takes an absolute path too.

Caveats

  • skillDir() is asynchronous, and an app's skills takes the skill, not a promise. Load the folders before you build the app: see Usage.
  • The name is the skill's. A name that isn't the folder's name logs a warning, and the skill is served under its name.
  • A skill folder can't hold another skill. A SKILL.md in any folder below it is refused: see Troubleshooting.
  • The files are read from disk while the server runs, so ship the folders with the server, at the paths resources holds.

External skill storage

class CatalogSkills extends ExternalSkillProviderBase { /* seven methods */ }
this.scope.skills.setExternalProvider(new CatalogSkills({ mode: "persistent", syncStateStore }));
await this.scope.skills.syncToExternal();

ExternalSkillProviderBase connects the server's skills to storage outside it, like a database several servers share. You write the class that talks to the storage; FrontMCP calls it. Set skillsConfig.externalProvider on the server to initialize and install it at startup, or call this.scope.skills.setExternalProvider(provider) while the server runs. The provider must implement the whole ExternalSkillProviderBase interface.

Method to writeCalled for
fetchSkill(id)skills/load of a skill that isn't the server's, in read-only mode. Return the skill, or null.
fetchSkills(options)skills/list, in read-only mode.
searchExternal(query, options)skills/search, in read-only mode. Return results with metadata, score, availableTools, missingTools and source: "external".
upsertSkill(skill), deleteSkill(id)syncToExternal(), in persistent mode, for each skill that's new or changed since the last sync, and each that's gone. Skills added with registerSkillContent() are copied too.
countExternal(options), existsExternal(id)Counting and checking skills in the storage.

Each skill is a SkillContent, the same shape registerSkillContent() takes.

Constructor optionTypeDescription
mode"read-only" | "persistent"Required. See below.
syncStateStore{ load(), save(state), clear() }Where persistent mode keeps what it copied, with a hash of each skill, so the next sync copies only what changed. Without one, it's kept in the provider: a new provider, as after a restart, copies every skill again.
logger, defaultTopK, defaultMinScoreA logger, and the topK and minScore passed to searchExternal(): 10, unless the request's limit says otherwise, and 0.1.
Modeskills/list, skills/searchskills/loadsyncToExternal()
read-onlyAnswered by the storage alone: the server's own skills aren't listed or found.The server's own skills by id, the others from fetchSkill(), with every tool marked available.Does nothing, and returns null.
persistentThe server's own skills, as without storage.The server's own skills.Copies the server's skills to the storage, and returns { added, updated, unchanged, removed, failed, durationMs }: lists of ids, failed as { skillId, error }, and the time it took.

A skill that comes from the storage has no SKILL.md resource, and isn't in skill://index.json. Keeping skills in external storage shows both modes.

SkillCatalogSourceToken

static dynamicProviders() {
  return [{ provide: SkillCatalogSourceToken, useValue: { ready, notLoadedReason, pointers, actions } }];
}

A plugin that adds skills while the server runs, with registerSkillContent() and dynamicSkills: true, as Skilled OpenAPI does from its bundle, can provide a SkillCatalogSource under SkillCatalogSourceToken. The server's skill requests and resources then wait for the plugin's skills, say when they haven't loaded, and can point the model to the plugin's own tools. Provide it from the plugin's dynamicProviders(): a provider in @Plugin({ providers }) isn't seen. New in 1.11.1.

MemberTypeDescription
ready()() => Promise<void>Required. Resolves once the plugin has registered its skills. The initialize and server/discover instructions, skills/list, skills/search, skills/load, skill://index.json and each SKILL.md wait for it. A rejection is logged, and the skills registered so far are served.
notLoadedReason()() => string | undefinedWhy the plugin's skills aren't loaded once ready() has settled, like a first download that failed; undefined once they are. See below.
pointers{ header, truncationHint, compact }What the instructions tell the model to load and find skills with, in place of skill://index.json: for a plugin that serves skills through tools of its own. compact follows This server has 2 skills: in the "compact" line, header heads the catalog of "append" and "prepend", and truncationHint ends a catalog cut short.
actions{ hint, visibleTo(skill, authInfo) }Lists a skill's actions at the end of its SKILL.md, under ## Actions: hint, then each action visibleTo() returns for the caller, with its summary, its description and its input and output JSON Schemas. Without it, SKILL.md lists no actions.

While notLoadedReason() gives a reason:

RequestAnswer
initialize, server/discoverThe instructions say This server's skills have not loaded yet (<reason>). Ask for them again shortly; the server sends notifications/skills/list_changed once they load., in place of the count or the catalog.
skills/list, skills/search, reading skill://index.jsonJSON-RPC error -32603, No skill bundle is loaded: <reason>, with data: { code: "SKILL_BUNDLE_NOT_LOADED", retryable: true }.
skills/load, reading a SKILL.mdThe same error for a skill that isn't found. A skill the server has loads.

The error is SkillBundleNotLoadedError, exported by @frontmcp/sdk. A server without a SkillCatalogSource answers as before. Changed in 1.11.1: before, these requests didn't wait for a plugin's skills, and answered as if the server had none of them until they loaded. Serving the skills a plugin adds shows each case.


Usage

Serving a skill

Register the skill next to the tools it uses. Open the Tests tab:

Open
import { Skill } from "@frontmcp/sdk";

@Skill({
  name: "triage-ticket",
  description: "Decide a new support ticket's priority.",
  instructions: `1. Read the ticket with get_ticket.
2. Set its priority with set_priority: high if the customer can't work, normal otherwise.`,
  tools: ["get_ticket", { name: "set_priority", purpose: "Record the priority", required: true }],
  parameters: [{ name: "ticketId", description: "The ticket to triage, like T-1", required: true }],
})
export class TriageTicket {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

The Call tab shows SKILL.md, the way a client reads it. A client that supports skills reads skill://index.json to see which skills there are, and the SKILL.md of one that fits the task. Teaching the Model Skills follows a client through it. A client that doesn't still gives its model the server's instructions, which point to the index, as the last test shows; a server with instructions of its own gets the line after them. Changed in 1.10.16: before, the default instructions included every skill's name and description. Set skillsConfig.injectInstructions: "append" to include the full catalog.

Choosing resource annotations

Use resourceAnnotations: "off" for a client that accepts no resource annotations, or "full" to include the numeric priority:

Skill resource annotations

Example 1 of 2

off

Open
import { App, FrontMcp, Skill } from "@frontmcp/sdk";

@Skill({ name: "triage-ticket", description: "Decide a ticket's priority.", instructions: "Read the ticket and set its priority." })
class TriageTicket {}

@App({ name: "Help Desk", skills: [TriageTicket] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  skillsConfig: { resourceAnnotations: "off" },
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Link to this example

Searching and loading skills

skills/search and skills/load are FrontMCP's own requests, for clients that know them: search by words, then load the skills that fit. A test sends them with mcp.raw.request():

Open
import { App, Skill, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "get_ticket", description: "Get a support ticket by id.", inputSchema: { id: z.string() } })
export class GetTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    return { id, title: "Cannot log in since this morning" };
  }
}

@Skill({
  name: "triage-ticket",
  description: "Decide a new support ticket's priority and who handles it.",
  instructions: "1. Read the ticket with get_ticket.\n2. Set its priority with set_priority.\n3. Assign it with assign_ticket.",
  tools: ["get_ticket", "set_priority", "assign_ticket"],
  tags: ["support"],
})
export class TriageTicket {}

@Skill({
  name: "refund-duplicate-charge",
  description: "Refund a customer who was charged twice for the same invoice.",
  instructions: "1. Read the invoice.\n2. Refund every charge after the first, to the card it was paid with.",
  tags: ["billing"],
})
export class RefundDuplicateCharge {}

@App({ id: "help-desk", name: "Help Desk", tools: [GetTicket], skills: [TriageTicket, RefundDuplicateCharge] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

card is only in the refund skill's instructions, and skills/search finds the skill by it; a query of stop words finds nothing. formattedContent repeats the instructions and each tool's schema, so a client that gives the model the Markdown asks for format: "markdown" and gets each part once; one that reads the fields keeps the default. Changed in 1.11.1: before, the instructions weren't searched, and the of and found both skills.

set_priority and assign_ticket aren't tools of this server, so the skill is incomplete: the model is told which steps it can't take. Search results say the same, with available: false, so a client can prefer skills it can finish. A tool the caller can't reach because of its surface counts as missing the same way, and a skill's SKILL.md can be read at its id as well as its name. Both changed in 1.8.5: before, such a tool was marked available, and only the name worked. tools also takes a tool's class, alone or as { tool, purpose, required }, and a class can't fall behind when the tool is renamed. (Changed in 1.9: before, a tool class stopped the server from starting.)

Ranking search with a decision model

The search index finds skills by their words, so a request worded differently from every skill finds nothing. With skillsConfig.decision, a decision model reads the request and the skills, and gives each skill a probability. Here a stand-in decides, since the Playground can't reach a model:

Open
import { App, FrontMcp, Skill } from "@frontmcp/sdk";
import { model } from "./model.example";

@Skill({ name: "triage-ticket", description: "Decide a new support ticket's priority.", instructions: "1. Read the ticket. 2. Set its priority." })
export class TriageTicket {}

@Skill({ name: "refund-duplicate-charge", description: "Refund a customer who was charged twice for the same invoice.", instructions: "1. Read the invoice. 2. Refund every charge after the first." })
export class RefundDuplicateCharge {}

@App({ id: "help-desk", name: "Help Desk", skills: [TriageTicket, RefundDuplicateCharge] })
export class HelpDeskApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  skillsConfig: { decision: { decider: model } },
})
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

I paid but want my money back shares no word with either skill, so the index alone finds nothing; the model's 0.92 is the refund skill's score, and the triage skill's 0.03 is under minProbability. In a real server, decider is decisionsApiDecider({ apiKey }), or a function of your own that asks another model. A model that fails, or takes longer than timeoutMs, leaves the results to the index, as the last test shows, and a warning is logged.

Hiding a skill

hideFromDiscovery keeps a skill out of every list, for a skill a client should only load when it already knows the id, such as one that another skill's instructions name. visibility: "http" keeps it out of MCP discovery, for the HTTP endpoints:

Open
import { App, Skill } from "@frontmcp/sdk";

@Skill({ name: "triage-ticket", description: "Decide a new support ticket's priority.", instructions: "1. Read the ticket." })
export class TriageTicket {}

@Skill({
  name: "write-internal-note",
  description: "Write a note on a ticket that only support agents see.",
  instructions: "Start the note with the date, and never paste the customer's password.",
  hideFromDiscovery: true,
})
export class WriteInternalNote {}

@Skill({
  name: "weekly-report",
  description: "Summarize the week's tickets for the support team lead.",
  instructions: "Count the tickets by priority, then list the ones still open.",
  visibility: "http",
})
export class WeeklyReport {}

@App({ id: "help-desk", name: "Help Desk", skills: [TriageTicket, WriteInternalNote, WeeklyReport] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Hiding a skill isn't access control: anyone who knows the id can load it. Changed in 1.12.1: before, skills/list listed visibility: "http" skills. It now leaves them out, including with includeHidden: true.

Leaving out skills with a hook

Every request and resource that serves skills runs the skills:filter flow, and a skill a hook drops from state.skills is treated as absent, as Skilled OpenAPI does for a bundle skill whose requiredAuthorities the caller lacks. Here a plugin leaves out the skills tagged staff:

Open
import { App, FlowCtxOf, FlowHooksOf, FrontMcp, Plugin, Skill } from "@frontmcp/sdk";

const SkillsFilter = FlowHooksOf("skills:filter");

@Plugin({ name: "staff-skills" })
class StaffSkills {
  @SkillsFilter.Did("filterSkills")
  async leaveOutStaffSkills(ctx: FlowCtxOf<"skills:filter">) {
    const { skills } = ctx.state.required;
    ctx.state.set("skills", skills.filter((skill) => !skill.metadata.tags?.includes("staff")));
  }
}

@Skill({ name: "triage-ticket", description: "Decide a new support ticket's priority.", instructions: "1. Read the ticket." })
class TriageTicket {}

@Skill({ name: "refund-runbook", description: "Refund a customer.", instructions: "1. Refund up to 500 EUR.", tags: ["staff"] })
class RefundRunbook {}

@App({ id: "help-desk", name: "Help Desk", skills: [TriageTicket, RefundRunbook] })
class HelpDeskApp {}

@FrontMcp({ info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp], plugins: [StaffSkills] })
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Changed in 1.11.1: before, resources/list didn't run the flow, so it still listed the dropped skill's SKILL.md, with its name and description, though skill://index.json, skills/list and reading it left the skill out.

Serving skills over HTTP

With skillsConfig: { enabled: true }, FrontMCP also serves skills at /skills, /llm.txt and /llm_full.txt, for programs that don't speak MCP. By default they take the same credential as the MCP endpoint, and leave out skills the caller's authorities refuse. The tests send HTTP requests through createFetchHandler(), the way a client would:

Open
import { App, FrontMcp, Skill } from "@frontmcp/sdk";

@Skill({ name: "triage-ticket", description: "Decide a new support ticket's priority.", instructions: "1. Read the ticket. 2. Set its priority." })
export class TriageTicket {}

@Skill({
  name: "refund-runbook",
  description: "Refund a customer.",
  instructions: "1. Check the order. 2. Refund up to 500 EUR.",
  authorities: "admin",
})
export class RefundRunbook {}

@App({ id: "help-desk", name: "Help Desk", skills: [TriageTicket, RefundRunbook] })
class HelpDeskApp {}

export const config = {
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  authorities: { profiles: { admin: { roles: { any: ["admin"] } } } },
  skillsConfig: { enabled: true },
};

@FrontMcp(config)
export default class Server {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

A static key carries no roles, so the admin skill is left out for it, over HTTP as over MCP. "api-key" and "bearer" give the endpoints credentials of their own, apart from the server's: Skills over HTTP has every option.

Giving a skill and an agent the same procedure

A skill has the client's model follow a procedure; an agent runs it on your server's model. You can offer both: keep the text in one constant, and give it to the skill as instructions and to the agent as systemInstructions. The tools go in the app, so the client's model can call them, and in the agent, so its model can:

Open
import { Agent, AgentContext, Skill, z } from "@frontmcp/sdk";
import { model } from "./model.example";
import { GetTicket, SetPriority } from "./ticket.tools";

export const TRIAGE_STEPS = `1. Read the ticket with get_ticket.
2. Set its priority with set_priority: high if the customer can't work, normal otherwise.`;

// For clients whose own model should do it
@Skill({
  name: "triage-ticket",
  description: "Decide a new support ticket's priority.",
  instructions: TRIAGE_STEPS,
  tools: ["get_ticket", "set_priority"],
})
export class TriageSkill {}

// For clients that would rather hand it off
@Agent({
  name: "triage",
  description: "Decide a new support ticket's priority. Pass the ticket's id.",
  systemInstructions: TRIAGE_STEPS,
  inputSchema: { ticketId: z.string() },
  tools: [GetTicket, SetPriority],
  llm: { adapter: model },
})
export class TriageAgent extends AgentContext {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

The skill is complete because both tools are in the app. With them only in the agent's tools, the client's model would be told they're missing. Teaching the Model Skills compares skills, agents and prompts.

Writing a skill as a function

skill() builds the same skill without a class. List what it returns in an app's skills:

Open
import { App, skill } from "@frontmcp/sdk";

export const refundPolicy = skill({
  name: "refund-policy",
  description: "How to answer a customer who asks for a refund.",
  instructions: "Refunds within 30 days of the charge are automatic. After 30 days, assign the ticket to billing.",
});

@App({ id: "help-desk", name: "Help Desk", skills: [refundPolicy] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Building a skill in code

A class that extends SkillContext can override two methods. loadInstructions() returns the instructions, and super.loadInstructions() reads the ones instructions names. build() returns the whole skill, SkillContent, and super.build() builds it from the options. Both have this.get() for the app's providers:

Open
import { Skill, SkillContext } from "@frontmcp/sdk";
import type { SkillContent } from "@frontmcp/sdk";
import { RefundPolicy } from "./refund-policy";

export const calls: string[] = [];

@Skill({
  name: "refund-duplicate-charge",
  description: "Refund a customer who was charged more than once for the same invoice.",
  instructions: "1. Read the invoice with get_invoice.\n2. Refund every charge after the first with refund_charge.",
  tools: ["get_invoice", "refund_charge"],
})
export class RefundDuplicateCharge extends SkillContext {
  async loadInstructions() {
    calls.push("loadInstructions");
    const steps = await super.loadInstructions();
    return `${steps}\n3. Refunds take ${this.get(RefundPolicy).businessDays} business days: tell the customer.`;
  }
}

@Skill({
  name: "escalate-outage",
  description: "Escalate a ticket that reports an outage.",
  instructions: "Page the on-call engineer with page_on_call.",
})
export class EscalateOutage extends SkillContext {
  async build(): Promise<SkillContent> {
    calls.push("build");
    const content = await super.build();
    return { ...content, description: `${content.description} Only for enterprise customers.` };
  }
}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

FrontMCP creates the class once, calls the methods when the server starts, and keeps what they return, as it keeps instructions read from a file or a URL. So this.get() reaches the app's and the server's providers, but there's no request, and nothing about the caller: every client reads the same skill. (Changed in 1.9.2: before, FrontMCP never created the class, and overrides had no effect.)

A description that build() returns is the skill's description everywhere: in SKILL.md, skills/load, skills/search, skill://index.json, resources/list and, with skillsConfig.injectInstructions: "append" as above, the skill list in the server's instructions. (Changed in 1.9.3: before, skill://index.json, resources/list and the skill list in initialize's instructions kept the option's description.)

Loading a skill from a SKILL.md folder

A skill written for other agents is often a folder: a SKILL.md, and the files its steps refer to. skillDir() serves it as it is. Here skills/triage-ticket/ holds a SKILL.md, one file in references/, one in examples/, a script and a spreadsheet:

skills/triage-ticket/SKILL.md
---
name: triage-ticket
description: Decide a new support ticket's priority and who handles it.
license: Apache-2.0
allowed-tools: get_ticket set_priority
metadata:
  owner: support-team
tags:
  - support
tools:
  - get_ticket
  - name: set_priority
    purpose: Record the priority
parameters:
  - name: ticketId
    description: The ticket to triage, like T-1
    required: true
---

1. Read the ticket with get_ticket.
2. Pick the priority as references/priorities.md says.
3. Set it with set_priority.
skills/triage-ticket/references/priorities.md
---
name: priorities
description: How to pick a ticket's priority
---

- high: the customer can't work.
- normal: everything else.

skillDir() returns a promise, so load the folder before you build the app, and give it a path to the folder:

main.ts
import "reflect-metadata";
import { resolve } from "node:path";
import { App, FrontMcpInstance, skillDir } from "@frontmcp/sdk";
import { GetTicket, SetPriority } from "./ticket.tools";

async function main() {
  // Resolve from the working directory explicitly
  const triage = await skillDir(resolve("skills/triage-ticket"));

  @App({ id: "help-desk", name: "Help Desk", tools: [GetTicket, SetPriority], skills: [triage] })
  class HelpDeskApp {}

  await FrontMcpInstance.bootstrap({ info: { name: "help-desk", version: "1.0.0" }, apps: [HelpDeskApp] });
}

main();

resources/list has skill://index.json and skill://triage-ticket/SKILL.md, as for a declared skill. A client that reads that SKILL.md gets the frontmatter rebuilt from the options, without tags, the steps, and a table of the references:

---
name: triage-ticket
description: Decide a new support ticket's priority and who handles it.
license: Apache-2.0
allowed-tools: get_ticket set_priority
metadata:
  owner: support-team
tools:
  - get_ticket
  - name: set_priority
    purpose: Record the priority
parameters:
  - name: ticketId
    description: The ticket to triage, like T-1
    required: true
    type: string
---

1. Read the ticket with get_ticket.
2. Pick the priority as references/priorities.md says.
3. Set it with set_priority.

## References

| Reference | Description |
| --------- | ----------- |
| `priorities` | How to pick a ticket's priority |

Then it reads skill://triage-ticket/references/priorities.md, and gets the two lines without their frontmatter. skill://triage-ticket/scripts/check-sla.sh comes back as text, skill://triage-ticket/assets/teams.csv as a base64 blob, and skill://triage-ticket/references/escalation.md, which isn't in the folder, fails with Resource not found. skills/load returns the same steps and table, with both tools available. The Playground has no file system, so this was run in Node, with a client sending each request over HTTP.

Keeping skills in external storage

A help desk run as several servers can keep its skills in one catalog that each server reads, or copy each server's skills to it. Here the catalog is a Map, standing in for a database, and sync_skill_catalog copies the server's skills to it. The tests also run the other mode, where the catalog answers the skills requests:

Open
import { SkillRegistry, Tool, ToolContext } from "@frontmcp/sdk";
import { CatalogSkills, syncState } from "./skill-catalog";

@Tool({ name: "sync_skill_catalog", description: "Copy this server's skills to the team's shared skill catalog", inputSchema: {} })
export class SyncSkillCatalog extends ToolContext {
  async execute() {
    const skills = this.scope.skills as SkillRegistry;
    if (!skills.hasExternalProvider()) {
      skills.setExternalProvider(new CatalogSkills({ mode: "persistent", syncStateStore: syncState }));
    }
    const result = await skills.syncToExternal();
    return { added: result?.added, updated: result?.updated, unchanged: result?.unchanged, removed: result?.removed };
  }
}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

persistent mode leaves the server's skills as they were and copies them out: the first sync adds triage-ticket, the next finds it unchanged, because the sync state holds a hash of each skill. In read-only mode the catalog takes over skills/list and skills/search, so triage-ticket isn't listed, though it still loads by id. A skill from the catalog loads with every tool marked available, even get_invoice, which this server doesn't have, and has a readable SKILL.md, also linked from skill://index.json. Changed in 1.9.5: before, external read-only skills had neither.

Serving the skills a plugin adds

A plugin that downloads its skills, like the runbooks below, has none until the download succeeds. With a SkillCatalogSource, the server says so, and a client asks again rather than taking the server for one without them. Here the first download failed, so reading skill://index.json, in the Call tab, answers an error, and pull_runbooks stands in for the retry that succeeds:

Open
import { DynamicPlugin, Plugin, SkillCatalogSourceToken, Tool, ToolContext } from "@frontmcp/sdk";
import type { SkillCatalogSource, SkillContent } from "@frontmcp/sdk";

export const download: { failure?: string } = { failure: "the runbook service answered 503" };

const refundOrder: SkillContent = {
  id: "refund-order",
  name: "refund-order",
  description: "Refund a customer's order.",
  instructions: "1. Check that the order was paid.\n2. Refund it with refundOrder.",
  tools: [],
  tags: ["billing"],
  bundleVersion: "2026-11-01",
  actions: [
    {
      actionId: "refundOrder",
      summary: "Refund an order.",
      inputJsonSchema: { type: "object", properties: { orderId: { type: "string" } }, required: ["orderId"] },
      outputJsonSchema: { type: "object" },
    },
  ],
};

const source: SkillCatalogSource = {
  ready: async () => {},
  notLoadedReason: () => download.failure,
  actions: {
    hint: "Run an action with `run_action`.",
    visibleTo: async (skill) => skill.actions ?? [],
  },
};

@Tool({ name: "pull_runbooks", description: "Download the runbooks again", inputSchema: {} })
export class PullRunbooks extends ToolContext {
  async execute() {
    await this.scope.skills.registerSkillContent(refundOrder);
    download.failure = undefined;
    return { loaded: [refundOrder.id] };
  }
}

@Plugin({ name: "runbooks", dynamicSkills: true, tools: [PullRunbooks] })
export class RunbooksPlugin extends DynamicPlugin<object> {
  static dynamicProviders() {
    return [{ provide: SkillCatalogSourceToken, useValue: source }];
  }
}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

While notLoadedReason() gives a reason, the requests that list skills answer the retryable error, and a request for a skill the server doesn't have yet answers it too; triage-ticket, the server's own, still loads. Once the runbooks load, skills/search and skills/list return each one's bundleVersion, its tags filter the search, and its SKILL.md ends with the actions visibleTo() returns for the caller, so a client that reads the resource knows what it can run without loading the skill. A SkillCatalogSource with pointers also changes what the instructions say to load skills with: Skilled OpenAPI's say load_skill and search_skill. Changed in 1.11.1: before, the plugin's skills didn't say they hadn't loaded, a runtime skill had no tags, and its SKILL.md listed no actions.

Connecting for skills only

A planner agent that only chooses which skills to run doesn't need the tools in its context. A client that opens its session with ?mode=skills_only on the URL of its initialize request gets an empty tools/list:

Request, in skills-only modeAnswer
tools/list{ "tools": [] }
tools/callRefused with Tool "<name>" not found, including Skilled OpenAPI meta-tools.
resources/listskill://index.json and each skill's SKILL.md, as without the mode.
skills/search, skills/list, skills/loadAs without the mode. skills/load still marks the tools available.

The mode works on every transport and protocol revision, for anonymous callers too. A client before MCP 2026-07-28 sets it on the URL of its initialize request, and the session keeps it. Under 2026-07-28, which has no sessions, each request sets it on its own URL, as the tests below do with createFetchHandler(), which runs this Playground. A tool's own this.callTool() still runs other tools. Changed in 1.9.5: before, the mode only hid tools/list, only in a session whose caller had a JWT the server verified, and tools/call still ran tools.

Open
import { App, Skill, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "get_ticket", description: "Read a support ticket", inputSchema: { id: z.string() } })
export class GetTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    return { id, title: "Cannot log in" };
  }
}

@Skill({
  name: "triage-ticket",
  description: "Decide a new support ticket's priority.",
  instructions: "1. Read the ticket with get_ticket.\n2. Say whether the customer can work.",
  tools: ["get_ticket"],
})
export class TriageTicket {}

@App({ id: "help-desk", name: "Help Desk", tools: [GetTicket], skills: [TriageTicket] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.


Troubleshooting

SKILL_SESSION_LIMIT

The server already holds 10,000 activated MCP skill sessions. End unused MCP sessions with DELETE before activating another; existing activations remain enforced. See skill sessions.

@FrontMcp invalid metadata for "skillsConfig": …

A skillsConfig field has an invalid value. Check the field and accepted values in the message: injectInstructions and resourceAnnotations accept only the modes above. Changed in 1.10.16: before, invalid skillsConfig raised a bare ZodError; it now raises InvalidDecoratorMetadataError.

Skill '…' failed tool validation: missing tools […]

The server doesn't start, because a skill with toolValidation: "strict" names a tool that isn't in tools/list. Add the tool to an app's tools, fix the name, or leave toolValidation at "warn", which logs a warning and serves the skill with the tool marked available: false. To let the server start while keeping "strict" on the skill, set skillsConfig: { failOnInvalidSkills: false } on the server: it logs an error instead. Changed in 1.9: before, "strict" didn't stop the server.

Open
import { App, Skill, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "get_ticket", description: "Get one support ticket by its id", inputSchema: { id: z.string() } })
export class GetTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    return { id, status: "open" };
  }
}

@App({ id: "help-desk", name: "Help Desk", tools: [GetTicket] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Invalid tool class '…'. Tool class must be decorated with @Tool and have a name property.

The server doesn't start, because tools lists a class that isn't a tool: it has no @Tool. List the tool's class, or its name. Before 1.9, every class failed this way, even a tool's, with an empty name: Invalid tool class ''.

Skill name must be kebab-case

The server doesn't start, because a skill's name has uppercase letters, underscores or spaces, or starts or ends with a hyphen. Use lowercase words joined by hyphens, like triage-ticket.

skills/load fails with ENOENT or fetch failed

The skill's instructions come from a file or a URL that couldn't be read. FrontMCP reads them when the server starts, but a failure doesn't stop it: the skill is left out of skills/list, and each request that needs it tries again, so skills/load fails with JSON-RPC error -32603 and ENOENT: no such file or directory, open '…', fetch failed, or, for a URL that answers with an error, Failed to fetch skill instructions from "…": 404, and reading its SKILL.md fails too. A relative file path is relative to the file that declares the skill, not to where the server runs. Check the path, or that the server can reach the URL. The Playground can do neither.

No skill bundle is loaded: …

A plugin that adds skills at runtime, like Skilled OpenAPI, hasn't loaded them yet: its first download is running, or failed for the reason after the colon. skills/list, skills/search and reading skill://index.json answer JSON-RPC error -32603 with data: { code: "SKILL_BUNDLE_NOT_LOADED", retryable: true }, and skills/load and reading a SKILL.md answer it for a skill the server doesn't have yet. Ask again later: the server sends notifications/skills/list_changed once the skills load. If it keeps failing, the reason says what to fix, like a bundle URL the server can't reach. See SkillCatalogSourceToken. New in 1.11.1: before, these requests answered as if the server had none of the plugin's skills.

Resource not found: skill://…/SKILL.md

The client read a SKILL.md that isn't served. Check, in order:

  1. The skill is in an app's skills, and the app is in @FrontMcp({ apps }).
  2. The URI uses the skill's name, or its skillPath joined with /, not its id.
  3. The skill doesn't set hideFromDiscovery: true or visibility: "http", and its availableWhen matches where the server runs. Such skills have no resource. See Hiding a skill.
  4. The server doesn't set skillsConfig: { mcpResources: false }.
  5. No hook on the skills:filter flow leaves the skill out for this caller: see Leaving out skills with a hook.

A tool shows as available: false

skills/load marks a tool available only if it's in the server's tools/list. Check the name as the tool spells it, and that the tool is in an app's tools: a tool that only an agent has doesn't count. A missing tool doesn't stop the server unless the skill sets toolValidation: "strict": see Skill '…' failed tool validation.

A skill isn't listed, and can't be loaded

The skill has an availableWhen that doesn't match where the server runs, or a surface that leaves out "mcp". Either way, FrontMCP doesn't serve it to MCP clients: it's missing from skills/list, skills/search and resources/list, skills/load warns Skill "…" not found, and reading its SKILL.md fails with -32602.

Open
import { App, Skill } from "@frontmcp/sdk";

@Skill({ name: "triage-ticket", description: "Decide a new support ticket's priority.", instructions: "1. Read the ticket." })
export class TriageTicket {}

// 🚩 This server doesn't run on Deno
@Skill({
  name: "restart-importer",
  description: "Restart the stuck ticket importer.",
  instructions: "1. Stop the importer. 2. Start it again.",
  availableWhen: { runtime: ["deno"] },
})
export class RestartImporter {}

// For the server's own agents, not for MCP clients
@Skill({
  name: "merge-duplicates",
  description: "Merge duplicate tickets into one.",
  instructions: "1. Keep the oldest ticket. 2. Move the replies. 3. Close the others.",
  availableWhen: { surface: ["agent"] },
})
export class MergeDuplicates {}

@App({ id: "help-desk", name: "Help Desk", skills: [TriageTicket, RestartImporter, MergeDuplicates] })
export class HelpDeskApp {}

Starting FrontMCP in your browser…

FrontMCP starts when this example comes into view.

Remove availableWhen, or change it to match where the server runs, to offer the skill everywhere.

Changed in 1.8.5: before, a skill excluded by where the server runs was still in skills/list and skills/search, and one hidden by surface still had its SKILL.md in resources/list.

Invalid skill "…": SKILL.md not found in directory

skillDir() found no SKILL.md in the folder it was given. Relative paths resolve against the calling file, then the working directory. Check that the folder has a SKILL.md. Changed in 1.9.5: before, relative paths were looked up from the filesystem root. The other errors skillDir() throws name what's missing, like Invalid skill "triage-ticket": SKILL.md is missing required 'description' field in frontmatter, or SKILL.md has no body content for instructions for a file with nothing after its frontmatter.

Skill name "…" does not match directory name "…"

A warning from skillDir(): the name in SKILL.md isn't the folder's name. The skill loads anyway, under its name: a folder refund-policy/ whose SKILL.md says name: refunds is served at skill://refunds/SKILL.md. Rename one of them, as the Agent Skills format expects them to match.

Skill directory contains nested SKILL.md files

skillDir() refused the folder because a folder inside it holds a SKILL.md too: Invalid skill "triage-ticket": Skill directory contains nested SKILL.md files (forbidden by SEP-2640 §Resource Mapping): references/escalation/SKILL.md. A skill's files are served under its skill:// path, so a skill inside another would make the same URI mean two things. Move the inner skill to a folder of its own, beside the other, and load each with skillDir().

?mode=skills_only still lists every tool

For session protocols, put ?mode=skills_only on the initialize URL. Under MCP 2026-07-28, put it on each request. Changed in 1.9.5: the mode works with every auth mode and with createFetchHandler(); before, those cases could still list tools.

See Connecting for skills only.

Report a docs issue · Report a security concern privately