Skills and Tools

Skills and tools add reusable procedures, knowledge, and external services to a Device Agent, such as inspection reports or energy-saving advice. The current model and connection supply the device’s own state, actions, and events.

When to Use Them

Confirm the capabilities supplied by the current model, then add skills or tools as needed.

Goal	Recommended option
Add an action the device can perform, such as setting temperature, turning power on or off, or switching mode	Configure commands, services, or writable properties in the model
Add status or events the device reports, such as humidity, cooling state, or abnormal alarms	Configure properties and events in the model
Make the Device Agent answer through a fixed process, such as an inspection report, troubleshooting checklist, or energy-saving recommendation	Import and enable a skill
Let the Device Agent access external information or run independent logic, such as energy policy, building-system state, or an alert service	Create and enable a tool
Let the Device Agent write local files or run shell commands	Enable the corresponding tool permissions in Configuration

Use model capabilities for device operations. Use a tool to call an external system and a skill to organize the business procedure.

Import a Skill

A skill is a reusable instruction package. After a skill is enabled, users still make requests in natural language. The Device Agent loads the matching skill when needed and follows the workflow in that skill.

In the Skills tab, you can import, enable, disable, export, or delete user skills.

Skills are imported as .zip files. The archive must contain a folder with SKILL.md:

thermostat-inspection/
  SKILL.md
  references/
  templates/

SKILL.md must include name and description in frontmatter:

---
name: thermostat-inspection
description: Generate an inspection report from thermostat status and recent events.
---

# Thermostat Inspection

...

After importing and enabling the inspection skill, ask about the Quick Start thermostat:

Create an inspection report for the current thermostat using its recent status, alarm events, and recommended actions.

The user does not need to type use_skill. The Device Agent decides whether to load a skill based on the request and skill description. Built-in skills are provided by the runtime and are not managed in the user skill list.

Create a Tool

A tool wraps a callable action. It can run local logic or call another system. After a tool is enabled, users still make requests in natural language. The Device Agent decides whether to call the tool based on its name, description, and parameter schema.

In the Tools tab, you can view, enable, disable, or delete user tools, and open the tool editor to create a new tool.

Use the complete code example below in the editor.

The common steps are:

1. Open Skills and Tools, then switch to Tools.
2. Click New tool to open the editor side panel.
3. Edit the tool name, label, description, parameters, and execute logic.
4. Click Save and confirm the success message.
5. Return to the Tools tab, confirm that the tool appears in the list, and keep it enabled.

The following example recommends thermostat settings from the current temperature and humidity. It does not depend on an external endpoint, so it can be saved and triggered from a conversation directly. Device control still uses commands or writable state supplied by the current model.

import type { AgentTool } from "@earendil-works/pi-agent-core";
import type { AgentToolDescriptor } from "@device-agent/shared";
import type { Type as TypeboxType } from "@sinclair/typebox";

function recommendSettings(currentTemperature: number, humidity: number) {
  if (currentTemperature >= 30) {
    return {
      mode: "cool",
      targetTemperature: 24,
      reason: "The current temperature is high, so cooling and a lower target temperature are recommended.",
    };
  }

  if (currentTemperature <= 18) {
    return {
      mode: "heat",
      targetTemperature: 22,
      reason: "The current temperature is low, so heating and a comfortable target temperature are recommended.",
    };
  }

  if (humidity >= 70) {
    return {
      mode: "auto",
      targetTemperature: 24,
      reason: "Humidity is high, so auto mode is recommended so the device can adjust to the environment.",
    };
  }

  return {
    mode: "eco",
    targetTemperature: 24,
    reason: "The current temperature and humidity are comfortable, so energy-saving mode is recommended.",
  };
}

export default function (api: {
  registerTool(tool: AgentTool, descriptor: AgentToolDescriptor): void;
  Type: typeof TypeboxType;
}) {
  const { registerTool, Type } = api;
  registerTool({
    name: "recommend_thermostat_settings",
    label: "Recommend thermostat settings",
    description: "Recommend target temperature and mode from the thermostat's current temperature and humidity. Use only when the user asks for energy-saving advice, comfort adjustment, or thermostat adjustment based on current state.",
    parameters: Type.Object({
      currentTemperature: Type.Number({ description: "Current temperature in Celsius" }),
      humidity: Type.Number({ description: "Current humidity percentage" }),
    }),
    async execute(_toolCallId, params: { currentTemperature: number; humidity: number }) {
      const recommendation = recommendSettings(params.currentTemperature, params.humidity);

      return {
        content: [
          {
            type: "text",
            text: `Recommended ${recommendation.mode} mode with target temperature ${recommendation.targetTemperature}°C. ${recommendation.reason}`,
          },
        ],
        details: recommendation,
      };
    },
  }, { execution: "read", approval: "none" });
}

In a platform deployment, each tool registration requires a second argument declaring its execution and approval policy. The recommendation tool only calculates a result, so it uses { execution: "read", approval: "none" }. Tools that change external data or perform actions use execution: "effect". Actions requiring user confirmation use approval: "required" and declare the parameter summary needed for approval. See API Reference for the full descriptor.

Declare parameter schemas with the Type builder provided on the api object. Type-only imports (import type ...) are supported; ordinary npm runtime imports are not. Explain when to use the tool and what input it requires. content provides the conversation result, while details provides structured output. To connect a business system, replace recommendSettings with a business API or another external service call.

Use From Conversation

Describe the goal, target device, and condition in the conversation:

Recommend energy-saving settings from the current temperature and humidity. If the recommendation looks right, update the target temperature and mode on the currently selected device.

The Device Agent can read the selected device state first, call recommend_thermostat_settings to calculate a recommendation, then use a thermostat command or writable state from the current model to control the device. The Device Agent selects the tool during the conversation; no manual tool call is required.

Built-in capabilities are provided automatically when the current context supports them. They do not need to be created from the Skills and Tools page.

Permissions and Validation

• Wait for a successful save after adding, editing, or disabling a tool. The change applies to subsequent requests; send a new request to verify it.
• Tool names can contain only letters, numbers, underscores, and hyphens, and cannot conflict with built-in tool names.
• Tool editor saving and deleting are controlled by permissions.tools.toolEditorMutations.enabled. Adjust permissions in the console; see Configuration for startup configuration rules.
• Do not expose the tool editor to untrusted users. Tool code runs on the server and should be reviewed like code.
• write_file and execute_command are high-privilege built-in tools. Configure them in Configuration.
• Skill: the response should follow the structure, workflow, or terminology from the skill.
• Tool: the conversation should show tool execution and return the tool result.
• Device control: confirm that the current model supplies the required command, service, or writable state, then verify the actual device result.

Use connected device capabilities

For choosing between device model capabilities, skills, and tools, see When to Use Them. Skills and tools remain subject to device scope and permissions. Before using them in automation, check Workflow Agent capabilities and Scheduled Task scope. Configure Voice Tools separately.