Skills and workspaces
Ship skills inside a module, turn augmentations on in a repository with .voxta/workspace.json, and offer workspace templates and requirement checks.
Embedded skills
A skill is a set of instructions the model loads only when the task needs them. Its name and one-line description are always visible. The body is read on demand through load_skill. Put instructions that only some chats need in a skill rather than in the module's chat context, which every reply pays for.
Put them in a Skills/ folder next to the .csproj:
Voxta.Modules.Weather/
├── Voxta.Modules.Weather.csproj
├── module.json
└── Skills/
├── weather-tools.md
└── forecast-format/
├── SKILL.md
└── examples.mdSkills/{name}.md is a one-file skill. Skills/{name}/SKILL.md can have files beside it, which the model loads by name. Voxta.Sdk.Modules embeds the folder (VoxtaEmbedSkills=false turns that off). Declare them on the definition:
builder.Register(new ModuleDefinition
{
// ...
Skills = ModuleSkills.EmbeddedResources(typeof(VoxtaModule)),
});Each skill starts with front matter:
---
name: weather-tools
description: "Calling the weather tools: units, places, when to ask first."
metadata:
augmentations: weather
tools: get_forecast get_alerts
---
Body...| Field | Notes |
|---|---|
name | Lowercase letters, digits and single hyphens, up to 64. |
description | When to load it. One line. |
metadata.augmentations | Offer it only in chats running one of these augmentation keys. Without it, any of the module's augmentations. |
metadata.tools | Deferred tools that load with the skill. |
Skills are offered in chats running the module's augmentations, read when the chat starts. A new build reloads the module, which ends those chats. The format is the one Claude Code and Codex use, so a SKILL.md written for them works. Needs a model with tool calling.
.voxta/workspace.json
A repository can say which augmentations chats working in it turn on. Commit .voxta/workspace.json at its root:
{
"augmentations": [
{ "key": "weather", "service": "Weather", "label": "Weather" },
{ "key": "tools.shell", "service": "Tools", "label": "Shell" }
]
}key: the augmentation key.service: the module'sServiceName, so a user missing it gets Add it.label: what the requirements list shows.- Users must Allow each key for their workspace before it turns on: the file comes with whatever was cloned. See What a folder asks for.
- Modules have no dependencies on each other. A folder that needs two modules asks for both.
The module template ships one asking for module_dev, tools.shell and workspace.
Contributing to workspaces
A module can help with a kind of project through two contracts, given with Contribute:
builder.Contribute<IWorkspaceTemplateProvider, MyWorkspaces>();
builder.Contribute<IWorkspaceRequirementsProvider, MyWorkspaces>();Both live in Voxta.Abstractions.Workspaces. The host asks for them on each use and keeps nothing, so the module stays reloadable.
Templates
public sealed class MyWorkspaces : IWorkspaceTemplateProvider
{
public IReadOnlyList<WorkspaceTemplate> GetTemplates() =>
[
new("weather-plugin", "Weather plugin", "https://github.com/owner/weather-plugin-template",
"A plugin for the Weather module."),
];
}| Parameter | Notes |
|---|---|
Id | Stable: links name it (/workspaces/new?template=…). |
Label | Shown in Start from. |
Repository | A git URL. |
Description | Shown under Start from when picked. |
A repository holding a dotnet new template (.template.config/template.json) is made into a project of the user's name, with its own git history. Voxta applies the part of the template format used for naming a project:
sourceName, replaced in file contents and file and folder names, as written and in lower case.- Derived symbols computed from the name (
valueSource: "name") throughforms:replace,chain,lowerCase,upperCase,firstLowerCase,firstUpperCase,identity. TheirreplacesandfileRename. - Parameter symbols, at their default value.
excludeglobs insources.
Other symbol types and conditional sources (modifiers) are skipped and listed to the user, as are files that are not UTF-8. Conditional blocks in files are not processed. Any other repository is cloned as it is.
Requirements
public sealed class MyWorkspaces : IWorkspaceRequirementsProvider
{
public async Task<IReadOnlyList<WorkspaceRequirement>> CheckAsync(string folder, CancellationToken cancellationToken)
{
if (!File.Exists(Path.Combine(folder, "weather.toml"))) return [];
var found = await FindToolAsync(cancellationToken);
return [found
? new WorkspaceRequirement("Weather CLI", true, "Found.")
: new WorkspaceRequirement("Weather CLI", false, "Not installed.", Url: "https://example.com/download")];
}
}| Parameter | Notes |
|---|---|
Label | What is needed. |
Met | Whether this machine has it. |
Detail | What was found, or what is wrong. |
Url | Where to get it: shown as Get it. |
ServiceName | A module to add, when a module is what is missing: shown as Add it. |
Checked when someone looks at the workspace (after creating it, when starting work), never per reply. Return an empty list for folders that are not your kind of project.
The Module Development module uses both: it offers the Voxta module template, and checks for the .NET SDK each module's global.json asks for.
module.json
A module's manifest: its id, its one version, its author and category, the Voxta versions it runs on, its platforms and its Python requirements, embedded in the DLL.
Installing and live reload
Load a module you are writing as a dev folder and reload it without restarting Voxta, install a built module from a .zip or .dll, and find out why one does not load.