@mastra/mcp-docs-server 1.2.18-alpha.3 → 1.2.18-alpha.5

package/.docs/docs/sandbox/skills.md

@@ -1,24 +1,14 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Workspace skills
+# Filesystem-backed skills
 
-Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io) - an open standard for packaging agent capabilities.
+Filesystem-backed skills are directories of reusable instructions and supporting files. Mastra discovers them from paths in the `skills` option, then makes them available to every agent using that configuration. Skills follow the [Agent Skills specification](https://agentskills.io).
 
-> **Note:** Workspace skills are discovered through a workspace and shared with every agent that uses it. To attach skills directly to one agent without requiring a workspace, use [agent skills](https://mastra.ai/docs/skills).
-
-## When to use skills
-
-Use workspace skills when your agent needs to:
-
-- Follow repeatable instructions for specialized tasks
-- Load detailed guidance only when it becomes relevant
-- Share instructions, reference files, scripts, and assets across agents
-- Discover capabilities from one or more directories
-- Search skill content alongside other workspace content
+Use [agent skills](https://mastra.ai/docs/skills) instead when you want to define a skill directly in one agent's code. An agent can use both types. If a direct agent skill and a filesystem-backed skill have the same name, the direct agent skill takes precedence.
 
 ## Quickstart
 
-Create a skill with a `SKILL.md` file:
+Create a directory with a `SKILL.md` file:
 
 ```markdown
 ---
@@ -31,203 +21,156 @@ description: Reviews code for bugs and readability issues
 Check the code for bugs, missing error handling, and unclear naming.
 ```
 
-Configure the skill directory on a workspace:
+Configure the directory:
 
 ```typescript
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
 
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+export const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './workspace',
+  }),
   skills: ['skills'],
 })
 ```
 
-Agents that use this workspace can now discover and load the `code-review` skill when needed.
+The `skills` path is relative to the filesystem root, so Mastra discovers `./workspace/skills/code-review/SKILL.md`. An agent using this configuration can now discover and load `code-review` when a request needs it.
 
 ## Skill structure
 
-A skill is a folder containing:
-
-- `SKILL.md`: Instructions and metadata for the agent
-- `references/`: Supporting documentation (optional)
-- `scripts/`: Executable scripts (optional)
-- `assets/`: Images and other files (optional)
+Each skill is a directory with a required `SKILL.md` file. It can also contain supporting files:
 
 ```plaintext
-skills/
-  code-review/
-    SKILL.md
-    references/
-      style-guide.md
-      pr-checklist.md
-    scripts/
-      lint.ts
+code-review/
+  SKILL.md
+  references/
+    style-guide.md
+  scripts/
+    lint.ts
+  assets/
+    review-template.md
 ```
 
-## `SKILL.md` format
+- `SKILL.md`: Metadata and instructions that Mastra loads when the agent selects the skill
+- `references/`: Documentation that the agent can read or search as needed
+- `scripts/`: Scripts used by the skill
+- `assets/`: Templates, images, and other supporting files
 
-Follow the official [skill specification](https://agentskills.io/specification) when creating your skill. Here is an example `SKILL.md` for a code review skill:
+Keep the main workflow in `SKILL.md`. Move detailed material to `references/` so the agent only reads it when needed.
 
-```markdown
----
-name: code-review
-description: Reviews code for quality, style, and potential issues
-version: 1.0.0
-tags:
-  - development
-  - review
----
-
-# Code Review
-
-You are a code reviewer. When reviewing code:
-
-1. Check for bugs and edge cases
-2. Verify the code follows the style guide in references/style-guide.md
-3. Suggest improvements for readability
-4. Run the linter using scripts/lint.ts
-
-## What to look out for
-
-- Unused variables and imports
-- Missing error handling
-- Security vulnerabilities
-- Performance issues
-```
+## `SKILL.md` format
 
-## Configuring skills
+The YAML frontmatter requires `name` and `description`. The `name` must match the skill directory name, contain at most 64 lowercase letters, numbers, or hyphens, not start or end with a hyphen, and not contain consecutive hyphens. The Markdown body contains the instructions returned to the agent when it loads the skill.
 
-You can specify multiple skill directories:
+Mastra also reads the optional `license`, `compatibility`, `user-invocable`, and `metadata` fields. See the [Agent Skills specification](https://agentskills.io/specification) for the complete package format and field guidance.
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: [
-    'skills', // Project skills
-    'team-skills', // Shared team skills
-  ],
-})
-```
+## How agents use skills
 
-You can also pass a direct path to a skill directory or `SKILL.md` file:
+When skills are configured, Mastra adds each skill's name, description, path, and source type to the system message. This lets the agent discover available skills without loading every instruction file into its context.
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: ['path/to/my-skill'],
-})
-```
+Mastra also gives the agent three tools:
 
-Glob patterns let you discover skills across nested directories:
+| Tool           | Does                                                                                      |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| `skill`        | Loads a skill's `SKILL.md` instructions and lists its reference, script, and asset files. |
+| `skill_read`   | Reads all or part of any file under the selected skill directory.                         |
+| `skill_search` | Searches skill instructions and reference files.                                          |
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: ['./**/skills'],
-})
-```
+Loading is stateless. The instructions remain in the conversation as a tool result, and the agent can call `skill` again if they leave the context after compaction.
 
-## How agents use skills
+## Configure skill paths
 
-When a workspace has skills configured, agents automatically get access to skill tools. Available skills are listed in the system message so the agent knows what's available, and the agent can load any skill on demand.
+The `skills` array accepts several path forms:
 
-The agent has three skill tools:
+| Path                          | Discovery behavior                                                |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `skills`                      | Scans each immediate subdirectory for a `SKILL.md` file.          |
+| `skills/code-review`          | Loads one skill directory directly.                               |
+| `skills/code-review/SKILL.md` | Loads one skill file directly.                                    |
+| `./**/skills`                 | Finds matching directories, then discovers skills under each one. |
+| `./**/SKILL.md`               | Finds and loads matching skill files.                             |
 
-- **`skill`**: Loads a skill's full instructions and returns them in the tool result. The agent calls this whenever it needs a skill's guidance.
-- **`skill_read`**: Reads a file from a skill's `references/`, `scripts/`, or `assets/` directory.
-- **`skill_search`**: Searches across all skill content. Uses BM25 or vector search when configured, otherwise falls back to basic text matching.
+Add more entries to discover skills from several roots, such as project, team, or package directories.
 
-Skill tools are registered when skills are configured. They aren't part of `WORKSPACE_TOOLS`, which configures filesystem, sandbox, search, and LSP tools.
+Glob traversal is limited to four directory levels below the glob base.
 
-This design is stateless, there is no activation state to track. If the skill instructions leave the conversation context (due to context window limits or compaction), the agent can call `skill` again to reload them.
+Paths use the configured filesystem when one is available. Without a filesystem, Mastra reads them from local disk relative to the application process's current working directory. An explicit [`skillSource`](#custom-skill-sources) replaces both defaults.
 
 ## Same-named skills
 
-When multiple skill directories contain a skill with the same name, all of them are discovered and listed. The agent sees every skill in its system message, along with each skill's path and source type, so it can tell them apart.
+Mastra lists every distinct filesystem-backed skill in the system message, including its path and source type. If several skills have the same name, a lookup by name uses this priority:
 
-When the agent activates a skill by name, tie-breaking determines which one is returned:
+1. Local project paths
+2. Managed paths under `.mastra/skills`
+3. External paths under `node_modules`
 
-1. **Source-type priority**: local skills take precedence over managed (`.mastra/`) skills, which take precedence over external (`node_modules/`) skills.
-2. **Unresolvable conflicts throw**: if two skills share the same name and the same source type (for example, two local skills that both use the name `brand-guidelines`), `get()` throws an error. Rename one or move it to a different source type to resolve the conflict.
-3. **Path escape hatch**: the agent can pass a skill's full path instead of its name to activate a specific skill, bypassing tie-breaking entirely.
+If multiple highest-priority candidates have the same source type, Mastra can't choose between them and throws an error. Rename one skill or move it to a different source type.
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: [
-    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
-    'skills', // local: also provides "brand-guidelines"
-  ],
-})
+The agent can bypass name-based resolution by passing the exact path shown in the system message to `skill` or `skill_read`. Paths with or without the trailing `/SKILL.md` work. If several configured paths resolve to the same canonical directory, Mastra treats them as aliases and lists the skill once.
 
-// get('brand-guidelines') returns the local copy (local > external)
-// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy
-```
+Direct [agent skills](https://mastra.ai/docs/skills) are resolved before filesystem-backed skills, so a direct skill wins when both types use the same name.
 
-## Skill search
+## Search skill content
 
-If BM25 or vector search is enabled on the workspace, skills are automatically indexed. Agents can search across skill content to find relevant instructions.
+When [BM25 or vector search](https://mastra.ai/docs/sandbox/search) is configured alongside skills, Mastra automatically indexes each skill's `SKILL.md` instructions and reference files. Scripts and assets aren't indexed.
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: ['skills'],
-  bm25: true,
-})
-```
-
-## Custom skill source
+Without BM25 or vector search, `skill_search` falls back to case-insensitive text matching across the instructions and references. This keeps skill search available without a separate search configuration, while indexed search provides ranking and semantic retrieval for larger collections.
 
-By default, skills are read from the workspace filesystem. For advanced use cases, provide a custom `skillSource` to load skills from a different backend.
+## Dynamic skill paths
 
-`VersionedSkillSource` serves published skill versions from a content-addressable blob store, so production agents use a specific published version without touching the live filesystem:
+Pass a synchronous or asynchronous function when the available paths depend on request context. This example adds development skills for users with the `developer` role:
 
 ```typescript
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
-import { VersionedSkillSource } from '@mastra/core/workspace'
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
 
 const workspace = new Workspace({
   filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: ['skills'],
-  skillSource: new VersionedSkillSource(versionTree, blobStore, versionCreatedAt),
-})
-```
-
-`VersionedSkillSource` accepts three parameters:
-
-- **`versionTree`** (`SkillVersionTree`): A manifest mapping relative file paths to blob entries (`{ entries: Record<string, { blobHash, size, mimeType?, encoding? }> }`).
-- **`blobStore`** (`BlobStore`): A content-addressable blob store instance that holds the actual file contents referenced by hash.
-- **`versionCreatedAt`** (`Date`): The timestamp when this skill version was published. Used as the modification time for all files in the version.
+  skills: ({ requestContext }) => {
+    const paths = ['skills']
 
-When `skillSource` is provided, it's used instead of the workspace filesystem for skill discovery.
+    if (requestContext?.get('user-role') === 'developer') {
+      paths.push('developer-skills')
+    }
 
-## Agent-level skills
+    return paths
+  },
+})
+```
 
-You can also attach skills directly to an agent without a workspace using `createSkill()` and the agent's `skills` config. When both agent-level and workspace-level skills exist, they merge, agent-level skills take precedence on name conflicts.
+Mastra resolves the function for each execution and gives the agent the skill set for that request. The returned paths support the same directory, file, and glob forms as a static array.
 
-See [Agent skills](https://mastra.ai/docs/skills) for details.
+## Custom skill sources
 
-## Dynamic skills
+Set `skillSource` when skills should come from a backend other than the configured filesystem or local disk. A custom source handles skill discovery and file reads for every configured path.
 
-For runtime skill paths based on context, pass a function:
+For example, `CompositeVersionedSkillSource` mounts published skill versions from a content-addressable blob store under directories where Mastra can discover them:
 
 ```typescript
+import { CompositeVersionedSkillSource, Workspace } from '@mastra/core/workspace'
+
+const skillSource = new CompositeVersionedSkillSource(
+  [
+    {
+      dirName: 'code-review',
+      tree: versionTree,
+      versionCreatedAt,
+    },
+  ],
+  blobStore,
+)
+
 const workspace = new Workspace({
-  filesystem: new LocalFilesystem({ basePath: './workspace' }),
-  skills: ctx => {
-    const paths = ['skills']
-    if (ctx.requestContext?.get('userRole') === 'developer') {
-      paths.push('dev-skills')
-    }
-    return paths
-  },
+  skills: ['.'],
+  skillSource,
 })
 ```
 
+An explicit `skillSource` doesn't fall back to the configured filesystem or local disk when a path is missing. See the [configuration reference](https://mastra.ai/reference/workspace/workspace-class) for the source interface and related options.
+
 ## Related
 
 - [Agent skills](https://mastra.ai/docs/skills)
-- [Agent skills specification](https://agentskills.io)
-- [Sandbox](https://mastra.ai/docs/sandbox/overview)
+- [Agent Skills specification](https://agentskills.io)
+- [Sandboxes](https://mastra.ai/docs/sandbox/overview)
 - [Search and indexing](https://mastra.ai/docs/sandbox/search)
 - [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)