Skills
This page introduces skills—the core modular units that define what an operator can do. Each skill provides metadata for decision-making and links to one or more actionable components that execute behavior within the system.
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)
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
Component | Description |
---|---|
friendly_name | Unique identifier for the skill |
description | Plain-language purpose, used for skill selection logic |
augmented_context | Data partitions and filters for adding context for skill use |
linked_skills | Optional follow-on or related skills |
controller | Final invoke that validates completion and transitions control |
Skills define what an operator can do, and when combined with context and logic, they become the foundation of intelligent, flexible behavior.
Updated 9 days ago