Skills

Skills are reusable Markdown-bodied capabilities you attach to an Agent block. They appear in the agent's system prompt as a compact <available_skills> listing, and the model can pull a skill's full body on demand by calling the built-in load_skill tool.

This is MyBotBox's take on the Claude-Skills pattern, adapted for multi-tenant workspaces.

Why use skills

Reuse. Define a capability once (a code-review checklist, a data-extraction recipe, a customer-tone guide) and attach it to as many agents as you like, across workflows.
Token efficiency. Only the short <skill name="...">description</skill> metadata is added to every agent turn. The full Markdown body — which can be many KB — is loaded only when the model decides it needs it.
Versioned. Every edit writes a skill_version row, so you have an audit trail of how the skill's instructions evolved.
Scoped. Skills are private, workspace-shared, or org-wide.

Visibility scopes

Visibility	Who can see it
`private`	Only the creator
`workspace`	All members of the owning workspace
`organization`	All org members across workspaces in that org

The picker on the Agent block lists the union of skills the current user can see; at runtime the resolver enforces these scopes again at the SQL layer.

Creating a skill

Open the Skills library — sidebar → Skills, or /workspace/<id>/skills.

Click "New Skill", give it a name + one-line description, choose visibility, and write the Markdown body. The slug is derived from the name (kebab-case) and is what the LLM sees as the skill's handle.

Optional: use the Improve button. Once the name is filled in, a sparkle Improve button appears next to the Description field and the Markdown body. Clicking it asks the model to draft (or rewrite) that field from the name and any current draft — see AI prompt enhancer below.

Save. Open the skill again to edit; each save bumps the version number (v1, v2, …) and writes a row to the version-history table.

AI prompt enhancer

The create modal and edit page each ship with two Improve buttons (sparkle icon) — one next to the Description field, one next to the Markdown body editor. They reuse the platform's existing wand pipeline (/api/wand-generate, gpt-4o via OpenAI/Azure), so no extra API key is required.

Button	What it generates
Description	A 1-2 sentence description, ≤200 characters, suitable for `<available_skills>`. No Markdown, no quotes.
Markdown body	A 250-600 word starter body with `## Purpose`, `## When to use it`, `## Steps`, `## Output format` sections. Numbered, concrete steps.

Behaviour:

Both buttons stay disabled until the name is filled — the model always has something concrete to anchor on.
If a field already has content, the enhancer treats it as a draft to improve rather than discarding it.
While a request is in flight, the affected field is disabled. On failure the existing error banner is reused; on success the field is filled in but not saved — review and click Save as usual.

Attaching a skill to an Agent

Open a workflow, click the Agent block, scroll to the Skills field.

Click + Add Skill. The popover groups available skills into Workspace, Organization, and Private sections.

Selecting a skill adds it as a chip below the trigger. Removing the chip detaches it. The total token cost of the attached skills is shown beneath the picker.

Runtime behaviour

When the agent runs, the executor:

Resolves the attached skill IDs to their slug + description, scoped to the workflow's workspace.

Appends a single <available_skills> block to the agent's system prompt:

<available_skills>
<skill name="code-review">Reviews diffs for null checks and missing tests</skill>
<skill name="data-extraction">Pulls structured fields out of unstructured email</skill>
</available_skills>

Registers a load_skill tool. The LLM can call it as load_skill({ skill_name: "code-review" }) to fetch the full Markdown body for that skill.

A skill that has been soft-deleted silently drops out of <available_skills>. The workflow keeps running — no error — and the agent simply behaves as if that skill was never attached.

Best practices

Cap descriptions to ~200 characters. They live in every agent turn's system prompt; longer descriptions multiply your token bill.
Move long instructions into the body, not the description. The body is loaded only on demand via load_skill.
Rename freely, but slugs are immutable. If you rename a skill, the display name in the library changes; the slug the LLM sees stays the same.
Keep workflow-specific instructions in the agent's systemPrompt field instead of creating one-off skills. Skills are for reusable, named capabilities.

Storage

Skills live in two Postgres tables:

skill — current state (id, slug, name, description, content, visibility, workspace/org pointers, current version, soft-delete tombstone).
skill_version — append-only history. One row per save.

See docs/database/CHANGELOG.md entry 0111 for the migration that introduced these tables and apps/sat/lib/skills/service.ts for the CRUD service layer.

Skills

On this page