Skills

A Skill is a prompt-shaping unit attached to a Bot. It carries a set of instructions and typed variable placeholders. When the gateway resolves a bot, it folds the skills into the system prompt or exposes them to the model on demand. Source: CRA-227

Read Concepts and Bots first.

What a Skill is

Field	Purpose
slug	Unique identifier within the org (/^[a-z][a-z0-9-]{2,39}$/).
displayName	Human-readable name shown in the control panel.
instructions	The prompt text for this skill. May contain ${variableName} placeholders.
variables	Typed variable definitions (string, number, or boolean) with optional defaults.
mode	always or on_demand. Controls how and when instructions and tools appear.

Skills are org-editable. The curated catalog ships SkillTemplate records (managed by Crafted AI); your org gets editable Skill copies when you clone a template or install an Industry Pack.

always vs on_demand

The mode field controls how a skill participates in request resolution.

always mode

Instructions are concatenated into the system prompt on every request where the bot is active. All tools declared by this skill’s plugins are exposed to the model in the normal tool list. Use always for guidance that must be present unconditionally — business rules, tone instructions, escalation logic.

on_demand mode

Instructions stay dormant. Instead of injecting the full skill text into the system prompt, the gateway exposes only tool stubs — {name, description} without input schemas — plus three meta-tools so the model can pull what it needs progressively. Source: CRA-238

Use on_demand for skills that represent large tool catalogs or detailed procedures the model rarely needs. This keeps injectedTokens low for the common case while still making the full capability reachable.

On-demand cuts token overhead

A bot with ten on-demand skills injects only the meta-tools and stub descriptions, not the full tool schemas. The model can discover and load exactly what it needs for the current turn. This is the recommended mode for large plugin catalogs.

The meta-tools

When any skill in the bot is in on_demand mode, the gateway injects three meta-tools alongside the tool stubs. The model uses these to discover and load skills progressively within a single turn. Source: CRA-238

crafted__search_tools

Searches across all dormant skills’ tool stubs by name and description. Returns the top matching results with a short schema preview.

{
  "name": "crafted__search_tools",
  "arguments": {
    "query": "appointment scheduling",
    "limit": 5
  }
}

The tool returns a ranked list of matching tool slugs with descriptions and schema previews, so the model can decide which tool to enable next.

crafted__enable_tool

Promotes a specific dormant tool into the active tool set for the rest of the current turn, surfacing its full input schema.

{
  "name": "crafted__enable_tool",
  "arguments": {
    "toolName": "acuity__create_appointment"
  }
}

After this call, the model can immediately call acuity__create_appointment with its full schema in subsequent iterations of the tool loop.

crafted__load_skill

Promotes an entire skill — injecting its full instructions text as a system message prefix and making all of its tools available for the rest of the turn.

{
  "name": "crafted__load_skill",
  "arguments": {
    "slug": "clinic-intake"
  }
}

Use this when the model determines a skill’s guidance is needed in full, not just one of its tools.

Namespace reservation

Plugin tool names cannot begin with crafted__. That prefix is reserved for meta-tools. Attempting to register a plugin tool whose name starts with crafted__ will be rejected.

Variables

Skills support typed variables that are substituted at install time (or when cloning from a template). Variable references in instructions follow the ${variableName} syntax.

Example skill template with variables:

{
  "slug": "realtor-local-market",
  "instructions": "You are a real estate assistant for ${agencyName}, specialising in ${primaryMarket}. Always include ${agencyName} branding in your sign-off.",
  "variables": [
    { "name": "agencyName", "type": "string", "required": true },
    { "name": "primaryMarket", "type": "string", "default": "residential properties" }
  ]
}

When you install a pack or clone a template, the install wizard collects values for required variables. After installation, edit variable values in the control panel under Skills → [skill name] → Variables.

Clone from template

Skill records are org-editable copies. SkillTemplate records are curated by Crafted AI and are read-only. When you clone a template, the wizard substitutes variables and creates an editable Skill in your org. Changes to your copy do not affect the template, and template updates from Crafted AI do not overwrite your edits.

To clone manually: open Skills → Browse templates in the control panel, find the template, click Clone, and fill in the variable values.

Next steps

• Read Bots to attach skills to a bot and configure gating mode.
• Read Marketplace to install an Industry Pack that comes with pre-configured skills.