@Skill

@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.

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 {}

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:

Optional:

instructions

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

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 whose description or tags match a query.

Returns { skills, total, hasMore, guidance }. Each skill has id, name, description, score (from 0 to 1), tags, tools (each { name, available }) and source: "local". 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.

skills/list

Lists skills, sorted by name.

Returns { skills, total, hasMore }, each skill with id, name, description, tags and priority.

skills/load

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

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.

Server options: skillsConfig

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

skillsConfig also has options for the HTTP endpoints (prefix, auth, apiKeys, jwt, llmTxt, llmFullTxt, api, cache), and injectInstructions, sep2640InInstructions, 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".

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.

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

What clients read

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 as SkillRegistry).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. Nothing in FrontMCP installs one: call setExternalProvider() on the scope's skill registry once the server runs, from a tool, say. A provider's factory runs too early, before the registry exists.

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

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.

Usage

Serving a skill

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

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 {}

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 list each skill by name and description, as the last test shows; a server with instructions of its own gets the list after them. (Changed in 1.9.3: before, server/discover left the list out.)

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():

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.",
  tags: ["billing"],
})
export class RefundDuplicateCharge {}

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

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.)

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:

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 {}

Hiding a skill isn't access control: anyone who knows the id can load it.

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:

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 {}

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:

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 {}

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:

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 {}

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:

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.` };
  }
}

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 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:

---
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.

---
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 an absolute path:

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

async function main() {
  // An absolute path: skillDir() doesn't resolve a relative one
  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:

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 };
  }
}

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 no SKILL.md to read.

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:

When it applies:

• Only for a session. The mode is kept in the session id, from the initialize request's URL. ?mode=skills_only on a later request changes nothing, and a 2026-07-28 request, which has no session, gets every tool with or without it. So does a client of createFetchHandler(), which opens no sessions.
• Only for a client that sends a JWT the server verifies. It took effect for a client whose token transparent auth verified. On a server without auth, or with public or static auth, whose keys aren't JWTs, FrontMCP opens the session while it checks the caller, before it reads the URL, and the session lists every tool: see Troubleshooting.

This was run against FrontMCP's own HTTP server in Node, since the Playground can't open a session.

Troubleshooting

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.

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 {}

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.

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 }.

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.

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 {}

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. In 1.9.4 that's also what any relative path gives, even one that's right: skillDir("./skills/triage-ticket") looks for the folder from the root of the file system. Pass an absolute path, like skillDir(resolve("skills/triage-ticket")), and check that the folder has a SKILL.md. 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

The mode takes effect only for a session that a client opens with ?mode=skills_only on its initialize request, signed in with a JWT that the server verifies, as with transparent auth. In 1.9.4 it's lost in these cases, and tools/list lists every tool:

• The server has no auth, or public or static auth. FrontMCP opens the session while it checks the caller, before it reads the URL.
• The client is on MCP 2026-07-28, or reaches the server through createFetchHandler(). Neither has a session to keep the mode in.
• The mode is on a later request rather than on initialize.

See Connecting for skills only.