Agent Skill

agent-skill defines one or more callable actions. Their names, descriptions, and parameter definitions are supplied to the model as available-tool context. The model selects an action through the runtime’s structured tool.request action.

The node has no normal input port. The runtime invokes it when a selected agent chooses one of its actions.

Configure skills in Node-RED: Agent Studio can edit some existing skill fields, but it does not currently provide complete action, parameter, output port, or flow-wiring management.

Properties

Property	Purpose
Name	Skill label shown in Node-RED and Agent Studio.
Outputs	Use one shared output or one output per action.
Actions	Names, descriptions, and parameter schemas exposed to the model.

Actions

Each action includes:

• Name: non-empty callable name, unique within the Agent Skill node.
• Description: explains what the action does and when to use it.
• Parameters: values the model must or may supply.

Use short, stable names such as search_web, get_customer, or send_email. Descriptions should distinguish similar actions and state important preconditions. Distinct names across all skills selected by one agent are also recommended so action selection and troubleshooting remain unambiguous.

The runtime tool ID has this form:

<skill-node-id>::<action-name>

Do not include :: in the action name. Duplicate names within the same Agent Skill node produce duplicate tool IDs and make later matching actions unreachable.

Parameters

Field	Purpose
Name	Message property supplied by the model.
Type	Describes the expected value as string, number, boolean, object, or array.
Target	Place the value at the message root or inside msg.payload.
Required	Tells the model that it should supply the value.
Default Value	Describes the intended fallback for an optional parameter.
Description	Explain meaning, format, and constraints.

These fields guide model output. The runtime does not currently validate parameter types, reject missing required values, or insert omitted defaults before invoking the flow. Validate important inputs and apply defaults in the Node-RED action flow.

Do not define parameters named action, sessionId, callId, or tool. These names are owned by the runtime and are added or overwritten during invocation.

Outputs

Per action is the default. It creates one output for every action, in the same order as the action list.

One sends every action through one output. Use msg.action or other flow logic to branch when necessary.

Invocation messages contain the selected parameters plus:

• msg.sessionId
• msg.callId
• msg.tool

Parameters targeted to payload are placed in msg.payload; root parameters remain at the message root.

Changing the action list can change the required number and meaning of output ports. Verify the wires after adding, removing, or reordering actions.

Return A Result

Wire the action output through the required flow logic, then into Agent In in Tool Response mode.

agent-skill
  -> action flow
  -> agent-in (Tool Response)
  -> original agent

Do not remove or overwrite the correlation fields before returning the result. Every branch, including validation and downstream failure paths, must eventually return a Tool Response. Logging an error or routing it only to a Catch node does not resume the waiting agent.

Manual Trigger Limitation

The current Node-RED editor includes a manual trigger button, but a skill invocation requires an action name and correlation fields supplied by the agent runtime. The button does not currently create a complete invocation and should not be used to test an action flow. This behavior is under development and may change.

Agent Studio Editing

Studio currently displays selected agent-skill nodes and can edit existing names, descriptions, parameter fields, and output mode. It cannot currently add or remove actions or parameters, and changing the action list or output mode does not manage Node-RED ports and wiring for you.

Studio also presents Type and Target as unrestricted text fields. Use Node-RED to maintain skill definitions and confirm supported types, targets, outputs, and wiring.

Design Guidance

• Prefer several focused actions over one action with ambiguous behavior.
• Keep action names unique and free of the :: separator.
• Reserve action, sessionId, callId, and tool for the runtime.
• Mark only genuinely necessary parameters as required.
• Describe IDs, date formats, and allowed values.
• Validate required values, types, and permissions before performing work.
• Return both successful and failed outcomes through Tool Response mode.
• Return concise structured results that the model can interpret.
• Never put credentials or private implementation details in descriptions.