Skills

What Is a Skill?

A skill is a self-contained capability an operator can use to interpret input, perform a task, or drive the next step in a workflow. Skills are defined as value objects in JSON and include both descriptive metadata and operational hooks.

Here’s an example of a complete skill definition:

{
  "organization_id": "org_melodyarc_production",
  "name": "ops_determine_topic",
  "partition": "operator_skills",
  "description": "",
  "tags": [
    "operator",
    "skill",
    "folder:cs_associate"
  ],
  "inputs": {
    "task.operator": {
      "evaluate": "=cs_associate"
    }
  },
  "value": {
    "description": "Determine the topic of the conversation. Only use when no topic exists, or the message suggests that the topic has or may have changed.",
    "linked_skills": [],
    "augmented_context": {
      "partitions": ["topics"],
      "tags": ["cs"]
    },
    "friendly_name": "Determine topic"
  },
  "search_resource_type": "value"
}

Skill Metadata Fields

The top-level metadata defines how the skill is stored, filtered, and used by the system:

• organization_id: Identifies the owning organization or workspace.
• name: A globally unique identifier for the skill. Required for internal referencing.
• partition: The storage bucket or namespace the skill belongs to (usually "operator_skills").
• description: Optional high-level documentation string (separate from the skill logic description).
• tags: Used for organizing, filtering, or scoping skills (e.g., folders, types, roles).
• inputs: Conditions that determine when this skill is applicable or what operator it belongs to.
• search_resource_type: Specifies the resource classification (typically "value" for skills).

Skill Logic (value block)

Inside the value object is where the actual behavior and decision logic lives.

Friendly Name

• friendly_name is a readable label used in interfaces and logs.

Description

• Used by the operator to determine when the skill should be used.
• Must be written in natural language and focused on guiding skill selection.

Augmented Context

• Provides access to scoped memory before execution.
  • partitions: Data namespaces to retrieve (e.g., "topics").
  • tags: Filters to restrict context relevance (e.g., "cs" for customer service).

Linked Skills

• An optional list of skills that may follow this one.
• Enables chaining or fallback logic as needed.

Skill Execution Lifecycle

Once a skill is selected by the operator, the system creates an action entity named after the skill. This entity represents the active execution of the skill and serves as the runtime container for its behavior.

Execution proceeds in two stages:

1. Invokes

Each skill triggers one or more invokes—triggers that perform real-world actions. Invokes may call APIs, run LLM prompts, interact with the MelodyArc portal (including human handoffs), send messages, or initiate workflows. For more information on invokes see Invokes.

2. Controller

A skill will also define a controller invoke. This is a final checkpoint that:

• Validates whether the skill has completed its intended function
• Signals readiness to proceed to the next skill (if others are queued)
• Performs any necessary transition logic or clean-up
• Can be used to update the operator state.

The controller only runs when its required inputs are satisfied.

Summary

Skills define what an operator can do, and when combined with context and logic, they become the foundation of intelligent, flexible behavior.