---
title: Workspace Skills
slug: /workspaces/skills
---

# Workspace Skills

:::warning Experimental
The Skills API is experimental and may change as the ecosystem evolves.
:::

Workspace skills are reusable instructions stored as `SKILL.md` files. They can be discovered, searched, activated, and injected into the agent prompt.

## Skill layout

Skills live under a root path (default: `/skills`) and each skill is a folder with a `SKILL.md`.

```
/skills
  /data-analysis
    SKILL.md
    references/
      schema.md
    scripts/
      analyze.py
    assets/
      sample.csv
```

You can also provide an async root resolver if skill paths are dynamic:

```ts
const workspace = new Workspace({
  skills: {
    rootPaths: async ({ workspace }) => ["/skills", `/skills/${workspace.id}`],
  },
});
```

### Runtime context in skills operations

Skill tool calls forward the current operation context to `WorkspaceSkills` internals.
This lets you build tenant-aware or account-aware skill routing.

```ts
const workspace = new Workspace({
  skills: {
    // operationContext is available when discovery is triggered from an agent operation.
    rootPaths: async ({ operationContext }) => {
      const tenantId = String(operationContext?.context.get("tenantId") ?? "default");
      return ["/skills/common", `/skills/tenants/${tenantId}`];
    },
  },
});
```

If you use tenant-scoped roots, prefer `autoDiscover: false` and call discovery with `refresh: true` from tools when tenant context changes.

## SKILL.md format

`SKILL.md` uses YAML frontmatter plus Markdown instructions:

```md
---
name: Data Analysis
description: Analyze CSV data with pandas and chart results.
version: "1.0.0"
tags:
  - data
  - python
references:
  - references/schema.md
scripts:
  - scripts/analyze.py
assets:
  - assets/sample.csv
---

When analyzing data:

1. Load CSV files with pandas.
2. Summarize key statistics.
3. Produce a chart and explain it.
```

Only files listed under `references`, `scripts`, or `assets` are readable via the skill file tools.

## Activating skills and prompt injection

When an agent has a workspace with `skills` configured, VoltAgent automatically injects a skills prompt into messages by default.

```ts
import { Agent, Workspace } from "@voltagent/core";

const workspace = new Workspace({
  skills: {
    rootPaths: ["/skills"],
  },
});

const agent = new Agent({
  name: "skills-agent",
  model,
  instructions: "Use workspace skills when relevant.",
  workspace,
});
```

The injected prompt is wrapped in `<workspace_skills>` tags and can include both available and activated skills.
It includes skill metadata (name, id, description). To read full `SKILL.md` instructions, use `workspace_read_skill`.

You can customize this behavior with `workspaceSkillsPrompt`:

```ts
const agent = new Agent({
  name: "skills-agent",
  model,
  instructions: "Use workspace skills when relevant.",
  workspace,
  workspaceSkillsPrompt: {
    includeAvailable: true,
    includeActivated: true,
    maxAvailable: 10,
    maxActivated: 5,
  },
});
```

Disable auto prompt injection:

```ts
const agent = new Agent({
  name: "skills-agent",
  model,
  instructions: "Use workspace skills when relevant.",
  workspace,
  workspaceSkillsPrompt: false,
});
```

If you provide a custom `hooks.onPrepareMessages`, auto injection is skipped unless `workspaceSkillsPrompt` is explicitly set (`true` or options object).
For advanced custom chaining, you can still call `workspace.createSkillsPromptHook(...)` manually.

## Skill tools

The toolkit provides:

- `workspace_list_skills`: list available skills
- `workspace_search_skills`: search skills (BM25/vector/hybrid)
- `workspace_read_skill`: read the full SKILL.md instructions
- `workspace_activate_skill`: activate a skill
- `workspace_deactivate_skill`: deactivate a skill
- `workspace_read_skill_reference`: read reference files
- `workspace_read_skill_script`: read scripts
- `workspace_read_skill_asset`: read assets

## Search notes

Skill search indexes the skill name, description, and instructions. Vector search requires an embedding model and vector adapter.
