Voxta docs
DevelopersModules

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

Skills/{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...
FieldNotes
nameLowercase letters, digits and single hyphens, up to 64.
descriptionWhen to load it. One line.
metadata.augmentationsOffer it only in chats running one of these augmentation keys. Without it, any of the module's augmentations.
metadata.toolsDeferred 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's ServiceName, 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."),
    ];
}
ParameterNotes
IdStable: links name it (/workspaces/new?template=…).
LabelShown in Start from.
RepositoryA git URL.
DescriptionShown 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") through forms: replace, chain, lowerCase, upperCase, firstLowerCase, firstUpperCase, identity. Their replaces and fileRename.
  • Parameter symbols, at their default value.
  • exclude globs in sources.

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")];
    }
}
ParameterNotes
LabelWhat is needed.
MetWhether this machine has it.
DetailWhat was found, or what is wrong.
UrlWhere to get it: shown as Get it.
ServiceNameA 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.

On this page