Skill Runtime API

Explore the isolated runtime lifecycle hooks, context injection payloads, and execution handlers required to implement secure agent skills.

Lifecycle Hook Handlers

Every skill package must export a standard execution entry interface. This ensures the SPM runtime host can securely trigger capabilities, inject environment tokens (like database credentials or API keys), validate inputs, and catch exceptions smoothly.

execute()async functionMandatory

The core entry function performing the actual capability logic. It receives:

params: The strict object parameters validated against your manifest's input schema.
context: System configurations, including credentials and active database connections.

validate()async functionOptional

Perform supplementary dynamic validations that JSON schemas cannot enforce (e.g. pinging an API host to verify key validity, or querying active files).

TypeScript Implementation Example

Here is a fully documented, production-grade template implementing standard execution lifecycle hooks:

index.ts

import { SkillContext, SkillExecuteResult } from "@agent-spm/types";

// 1. Declare strict Type parameter interfaces matching spm.yaml input
interface WeatherInput {
  city: string;
  units?: "celsius" | "fahrenheit";
}

interface WeatherOutput {
  temp: number;
  wind: string;
  condition: string;
}

/**
 * Perform supplementary dynamic validations
 */
export async function validate(params: WeatherInput, context: SkillContext): Promise<boolean> {
  if (!params.city || params.city.trim().length === 0) {
    throw new Error("Target city string parameter cannot be empty.");
  }
  return true;
}

/**
 * Main execution lifecycle hook
 */
export async function execute(
  params: WeatherInput,
  context: SkillContext
): Promise<WeatherOutput> {
  const apiKey = context.env.WEATHER_API_KEY;
  if (!apiKey) {
    throw new Error("Missing required credential environment: WEATHER_API_KEY.");
  }

  const units = params.units || "celsius";
  const url = `https://api.weather.dev/v1/current?q=${encodeURIComponent(params.city)}&key=${apiKey}`;

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Weather host responded with code: ${response.status}`);
  }

  const data = await response.json();

  // Return exactly conforming output object
  return {
    temp: units === "celsius" ? data.temp_c : data.temp_f,
    wind: `${data.wind_kph} kph`,
    condition: data.condition_text,
  };
}

Environment & Security Isolation

When executing in agent pipelines, skills operate under strict isolated execution sandboxes:

No Arbitrary Environment Access: Skills can ONLY read environment keys explicitly registered in their workspace configurations. They cannot scan host machine environment states.
CPU & Memory Sandboxing: Runtimes enforce memory limits (e.g. 512MB max for Node skills) and timeouts to prevent hanging infinite loops or recursive prompts.
Network Whitelisting: Optional configurations in spm.yaml restrict skills to communicate only with registered remote API domains.

PREVIOUSPackage Publishing