Skills

Skills give the assistant reusable instructions for a particular task, such as reviewing a document, preparing a report, or following your team's writing conventions. A skill contains a SKILL.md file and may include examples, templates, or scripts. Your skill library belongs to your account, and you choose which skills each chat can use.

A saved prompt inserts text into your message. A skill stays available to the conversation so the assistant can load its instructions when they are relevant. You can also request it by name. If you need to connect an inference engine or provider instead, use a plugin.

Add skills to a chat

Importing through the WebUI requires MCP usage (MCP_USE).

1. In the SoAI WebUI, open a conversation and select Chat configuration > Skills.
2. Select Add skill and choose a SKILL.md file, a skill ZIP, or a repository ZIP containing a collection.
3. Use View to read the instructions and inspect the supporting files.
4. Enable the skills you want this conversation to use, then select Save.

Importing adds every discovered skill to your library together; enabling skills for a chat requires Save. Closing the configuration without saving leaves the conversation's previous selection in place. A new conversation starts with no skills selected.

A leading invocation captures the following text as its arguments. For example, $review-notes draft.md binds draft.md. A leading stack such as $review-notes $summarize draft.md gives both skills the same trailing arguments. Inline mentions activate skills without treating the surrounding sentence as arguments. Plugin-qualified names, such as $plugin:review-notes, resolve only within the conversation's saved selection. Captured arguments remain fixed for accepted work, including replay and explicitly delegated instructions.

Save a Skills section in a chat configuration preset to reuse the same selection. Applying that preset stages the selection for review; select Save to use it in the conversation. A preset with an empty Skills section clears the selection, while a preset without that section leaves it alone. If a referenced skill has been removed, SoAI reports the skipped value instead of installing another skill with a similar name.

Use a skill

With tools enabled and a model that supports tool calling, the assistant can discover enabled skills from their names and descriptions, then load the relevant instructions through skill_read. SoAI makes that tool available for a turn with selected skills; you do not need to select it separately in the tool picker. Selecting a skill makes it available, but does not force the model to use it on every message.

Use $name in your message to request an enabled skill. For example, send Use $review-notes to review this draft. or begin with $review-notes followed by your request. SoAI has no slash commands, so a message that begins with /name is sent as ordinary text. Enable the skill and save before requesting it by name. Names inside code, quoted blocks, mathematical expressions, or link destinations are treated as content rather than requests to load a skill. Escape a dollar sign with a backslash when it belongs to ordinary text.

An explicit request loads the instructions even when automatic tool loading is unavailable. A skill that needs file, browser, or other tools still needs those tools to be enabled and supported by the model. Your direct instructions take precedence over the skill, and its contents do not grant permissions or bypass tool approvals.

The availability label explains whether the assistant can load a skill automatically, whether you can request it by name, or whether its author has disabled both methods. An unavailable explicit request is rejected before work is accepted. Check the name, saved selection, and availability label before sending again. An automatic-only skill cannot be requested by name; its author controls that behavior through the manifest's loading options.

Permissions and tool settings

Your signed-in account owns its library. Viewing, downloading, and deleting your skills do not require plugin administration. WebUI imports and changes to tool settings require MCP usage (MCP_USE). Automatic loading and supporting-file reads need an enabled tool runtime (TOOLS.MCP.ENABLED) and a model that supports tool calling. Open Chat configuration > Tools, enable tools, select at least one ordinary tool for the active mode, and select Save.

There is no separate skills permission or installation-wide skills switch. When automatic loading is unavailable, a permitted explicit request can still supply the instructions in Chat mode. Actions described by a skill, such as running a shell command, keep their own permissions and feature settings. See Permissions and approvals for those controls.

Supporting files and context

After activation, the assistant can use skill_read to read UTF-8 supporting text in bounded portions. Binary files return file information rather than their contents. Select View in Chat configuration > Skills and select a supporting filename to download it when you need to inspect or use it elsewhere.

Importing a skill does not install or run its scripts. To use complete supporting files in the workspace, open Chat configuration > Tools, select skill_materialize under Execute mode, enable tools, and select Save. Ask the assistant to load the skill and copy its files. Approve the write when the conversation requires approval. The tool copies the package into a new private folder and returns its workspace-relative path and file inventory, including binary files and empty folders. It does not install dependencies or run scripts; those steps use ordinary permitted execution tools.

Retrying the same copy operation returns its existing result. If its folder or workspace has changed, review the reported conflict; SoAI does not replace your files. Check the task result after an interruption, since stopping a turn can leave a completed copy. Deleting a skill from the library leaves workspace copies intact.

Activated instructions use the model's conversation context. If they do not fit, SoAI reports that the skill could not load rather than applying a partial set of instructions. Wait until the conversation is idle and compact older context, choose a model with a larger context window, or import a shorter replacement. Keep long reference material in supporting files so the assistant can read the parts it needs.

Change or remove a skill

Use the search field to find a skill by name or description. Disable it and save to stop using it in one chat, or select Delete and confirm to remove it from your library and future conversation selections. Removal takes effect immediately and is separate from the configuration's Save button.

Work already accepted keeps the skill content it started with, including when a skill is removed while the assistant is working, or while a prompt waits in the queue. Steering that work uses the same skill selection; a newly accepted prompt or regenerated reply uses the selection saved at that time. To replace a skill, remove the old one, import the revised package, and select it again in the chats and presets where you want it.

If another tab changes the selection while you are editing it, review the conflict before saving. Refresh to use the saved selection, or keep your draft after reviewing the newer selection. During a disconnect, SoAI retains your draft and waits for a current snapshot before allowing a save.

Imports and limits

A collection ZIP can contain nested skills under declared plugin paths or conventional skills/, .agents/skills/, .claude/skills/, and .codex/skills/ directories. A transport folder around a repository does not determine skill identity. All canonical skills under a declared conventional skill directory are discovered, including skills omitted from a plugin's partial registration list. Undeclared documentation examples and host mirrors are excluded. Conflicting copies fail the entire import. The Creating a skill guide covers the manifest and portable package layout.

Removed skills may still occupy storage while accepted work uses them. If an import reaches the library's capacity, remove unused skills and wait for work retaining their content to finish before retrying. A failed import leaves installed skills and saved conversation selections intact.

Import retains the skill packages and the supporting files they reference, without running scripts, installing dependencies, registering hooks, or connecting services. Collection materialization preserves source-relative positions and returns the actual skill directory together with its source root. Use that root for CLAUDE_PLUGIN_ROOT paths. Install or configure a missing prerequisite explicitly before running the workflow. Tool declarations never grant permissions; supported restrictions continue to apply to remaining actions and delegated tool selection. An allowed-tools list that omits skill_read still lets the assistant read the active skill's supporting files; list it under disallowed-tools to block those reads. Unsupported restrictive syntax must be corrected before activation.

If the upload response is lost, use its retry action before starting another import. Closing the dialog does not undo an import; reopen it to check the library. Use each skill's Delete action to remove it.

Skills are available in ordinary SoAI chats and their delegated work. They are not personal instructions for automations, messaging integrations, external inference API requests, or clients connected to SoAI's MCP server. A copied conversation history does not select or activate skills for the new conversation.

Related documentation

• Chat
• Creating a skill
• Prompts
• Agent mode, tool approvals, and checkpoints
• Conversation context, compaction, and history
• Built-in tool reference
• Access control