aradotso/skills/world2agent-protocol

---
name: world2agent-protocol
description: Skill for using World2Agent (W2A) — the open protocol that standardizes how AI agents perceive the real world via structured sensor signals.
triggers:
  - add a sensor to my agent
  - set up world2agent
  - how do I use W2A sensors
  - make my agent perceive real-world data
  - install a world2agent sensor
  - build a custom W2A sensor
  - configure world2agent in my project
  - stream real-time signals to my AI agent
---

# World2Agent (W2A) Protocol

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

World2Agent (W2A) is an open protocol that standardizes how AI agents perceive the real world. Sensors watch data sources and emit structured signals following the W2A schema. Your agent receives those signals and decides what to do. The architecture is always: **World → Sensor → Agent**.

---

## Installation

### Option 1: Claude Code Plugin (Fastest)

In an active Claude Code session:

/plugin marketplace add machinepulse-ai/world2agent-plugins /plugin install world2agent@world2agent-plugins /reload-plugins

Add sensors:

/world2agent:sensor-add @world2agent/sensor-hackernews /world2agent:sensor-add @quill-io/sensor-frontier-ai-news

Restart Claude Code with the plugin channel loaded:

```bash
claude --dangerously-load-development-channels plugin:world2agent@world2agent-plugins

Option 2: SDK / Code Integration

Install the core SDK and a sensor:

npm install @world2agent/sdk
npm install @world2agent/sensor-hackernews

---

Core Concepts

| Term | Description | |------|-------------| | Sensor | An npm package that watches a data source and emits W2A signals | | Signal | A structured JSON object emitted by a sensor (follows W2A schema) | | SensorHub | Catalog of all official and community sensors at world2agent.ai/hub | | Channel | A named stream that groups signals from one or more sensors |

---

Signal Format

Every W2A signal shares a common schema:

interface W2ASignal {
  id: string;                  // Unique signal ID (UUID)
  sensorId: string;            // e.g. "@world2agent/sensor-hackernews"
  sensorVersion: string;       // semver
  timestamp: string;           // ISO 8601
  type: string;                // e.g. "story.new", "price.alert", "news.post"
  priority: "low" | "medium" | "high" | "critical";
  payload: Record<string, unknown>; // Sensor-specific structured data
  meta?: {
    source?: string;           // URL or origin
    tags?: string[];
    confidence?: number;       // 0–1
  };
}

Example signal from the Hacker News sensor:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sensorId": "@world2agent/sensor-hackernews",
  "sensorVersion": "1.2.0",
  "timestamp": "2026-04-29T10:00:00Z",
  "type": "story.new",
  "priority": "medium",
  "payload": {
    "storyId": 39812345,
    "title": "Show HN: My open-source project",
    "url": "https://example.com",
    "score": 142,
    "author": "someone",
    "commentCount": 38
  },
  "meta": {
    "source": "https://news.ycombinator.com/item?id=39812345",
    "tags": ["show-hn", "open-source"]
  }
}

---

SDK Usage

Subscribing to Sensor Signals

import { W2AClient } from "@world2agent/sdk";
import { HackerNewsSensor } from "@world2agent/sensor-hackernews";

const client = new W2AClient();

// Register sensors
client.use(new HackerNewsSensor({
  filter: {
    minScore: 100,
    types: ["story.new", "story.trending"],
  },
}));

// Listen for signals
client.on("signal", (signal) => {
  console.log(`[${signal.priority}] ${signal.type}:`, signal.payload);
});

// Start receiving signals
await client.start();

Handling Specific Signal Types

import { W2AClient, W2ASignal } from "@world2agent/sdk";

const client = new W2AClient();

client.on("signal", (signal: W2ASignal) => {
  switch (signal.type) {
    case "story.new":
      handleNewStory(signal.payload);
      break;
    case "price.alert":
      handlePriceAlert(signal.payload);
      break;
    default:
      console.log("Unhandled signal type:", signal.type);
  }
});

function handleNewStory(payload: Record<string, unknown>) {
  const { title, score, url } = payload as {
    title: string;
    score: number;
    url: string;
  };
  console.log(`New story (score: ${score}): ${title} — ${url}`);
}

Multiple Sensors

import { W2AClient } from "@world2agent/sdk";
import { HackerNewsSensor } from "@world2agent/sensor-hackernews";
import { FrontierAINewsSensor } from "@quill-io/sensor-frontier-ai-news";

const client = new W2AClient({
  channelName: "my-agent-feed",
});

client.use(new HackerNewsSensor({ minScore: 50 }));
client.use(new FrontierAINewsSensor({ labs: ["openai", "anthropic", "google"] }));

client.on("signal", (signal) => {
  // Signals from all sensors arrive here with sensorId to distinguish source
  console.log(`From ${signal.sensorId}:`, signal.type, signal.payload);
});

await client.start();

---

Building a Custom Sensor

Install the build skill:

npx skills add https://github.com/machinepulse-ai/world2agent/skills/build-w2a-sensor

Or build manually in ~50 lines:

// src/index.ts
import { BaseSensor, W2ASignal, SensorConfig } from "@world2agent/sdk";

interface MyWeatherSensorConfig extends SensorConfig {
  city: string;
  apiKey?: string; // use process.env.WEATHER_API_KEY
  pollIntervalMs?: number;
}

export class WeatherSensor extends BaseSensor {
  private city: string;
  private apiKey: string;
  private pollInterval: number;

  constructor(config: MyWeatherSensorConfig) {
    super({
      id: "@myorg/sensor-weather",
      version: "1.0.0",
    });
    this.city = config.city;
    this.apiKey = config.apiKey ?? process.env.WEATHER_API_KEY ?? "";
    this.pollInterval = config.pollIntervalMs ?? 60_000;
  }

  async start(): Promise<void> {
    await this.poll(); // immediate first fetch
    setInterval(() => this.poll(), this.pollInterval);
  }

  private async poll(): Promise<void> {
    const res = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${this.apiKey}&q=${this.city}`
    );
    const data = await res.json();

    const signal: Omit<W2ASignal, "id" | "timestamp"> = {
      sensorId: this.meta.id,
      sensorVersion: this.meta.version,
      type: "weather.update",
      priority: data.current.temp_c > 35 ? "high" : "low",
      payload: {
        city: this.city,
        tempC: data.current.temp_c,
        condition: data.current.condition.text,
        humidity: data.current.humidity,
        windKph: data.current.wind_kph,
      },
      meta: {
        source: `https://www.weatherapi.com`,
        tags: ["weather", this.city.toLowerCase()],
      },
    };

    this.emit(signal); // BaseSensor handles id + timestamp
  }
}

package.json for your sensor

{
  "name": "@myorg/sensor-weather",
  "version": "1.0.0",
  "description": "W2A sensor for real-time weather data",
  "main": "dist/index.js",
  "keywords": ["w2a-sensor", "world2agent", "weather"],
  "peerDependencies": {
    "@world2agent/sdk": "^1.0.0"
  }
}

Publish it:

npm publish --access public

---

Configuration Reference

W2AClient Options

const client = new W2AClient({
  channelName?: string;        // Default: "default"
  logLevel?: "silent" | "info" | "debug"; // Default: "info"
  signalBufferSize?: number;   // How many signals to buffer. Default: 100
  onError?: (err: Error) => void;
});

Environment Variables

| Variable | Description | |----------|-------------| | W2A_LOG_LEVEL | Override log level (silent, info, debug) | | W2A_CHANNEL | Default channel name | | WEATHER_API_KEY | Example: API key for a weather sensor (sensor-specific) |

---

Common Patterns

Pattern: Agent reacts to high-priority signals only

client.on("signal", (signal: W2ASignal) => {
  if (signal.priority === "high" || signal.priority === "critical") {
    triggerAgentAction(signal);
  }
});

Pattern: Filter signals by sensor source

client.on("signal", (signal: W2ASignal) => {
  if (signal.sensorId === "@world2agent/sensor-hackernews") {
    const { title, score } = signal.payload as { title: string; score: number };
    if (score > 200) {
      notifySlack(`Hot HN post: ${title}`);
    }
  }
});

Pattern: Graceful shutdown

process.on("SIGINT", async () => {
  console.log("Shutting down W2A client...");
  await client.stop();
  process.exit(0);
});

Pattern: Logging all signals to a file

import { appendFileSync } from "fs";

client.on("signal", (signal: W2ASignal) => {
  appendFileSync(
    "signals.ndjson",
    JSON.stringify(signal) + "\n",
    "utf-8"
  );
});

---

SensorHub — Finding Sensors

Browse world2agent.ai/hub for the full catalog. Categories include:

• 📰 News — Hacker News, frontier AI lab posts, RSS feeds
• 📈 Markets — stock prices, crypto, economic indicators
• 🚨 Production — error alerts, uptime, deployment events
• 🌦 Weather — real-time conditions, forecasts
• 🤖 AI Labs — OpenAI, Anthropic, Google announcements

Fallback search via npm:

npm search w2a-sensor

---

Troubleshooting

Signals not arriving

• Confirm client.start() was called and awaited.
• Check sensor-specific config (API keys, filters).
• Set logLevel: "debug" to see internal sensor polling.

Claude Code plugin not loading

• Run /reload-plugins after install.
• Restart with --dangerously-load-development-channels plugin:world2agent@world2agent-plugins.

TypeScript type errors on payload

• payload is typed as Record<string, unknown> by design. Cast to your sensor's known shape: signal.payload as { title: string; score: number }.

Sensor emitting too frequently

• Increase pollIntervalMs in your sensor config.
• Add a deduplication check using signal.id or payload fingerprinting.

Unknown signal types at runtime

• Add a default case in your switch to log and handle gracefully.
• Check the sensor's docs on SensorHub for all emitted type values.

---

Key Links

• SensorHub — browse all sensors
• Signal format spec
• Architecture deep dive
• Build a sensor guide
• Multi-sensor guide
• Discord community