openclaw-workflowskill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Cromer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# OpenClaw WorkflowSkill Plugin
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node: >=20](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/matthew-h-cromer/openclaw-workflowskill/issues)
+
+> [!IMPORTANT]
+> **Pre-release.** This plugin tracks the [WorkflowSkill](https://github.com/matthew-h-cromer/workflowskill) spec, which is not yet frozen. Expect breaking changes as the spec evolves.
+
+Author, validate, run, and review WorkflowSkill workflows — without leaving the OpenClaw chat.
+
+1. Tell the agent what you need
+2. The agent writes, validates, and test-runs the workflow in chat
+3. Schedule it with cron — runs autonomously, no agent session needed
+
+## What it looks like
+
+> **You:** I want to check Hacker News for AI stories every morning and email me a summary.
+>
+> **Agent:** I'll author a WorkflowSkill for that. *(invokes `/workflowskill-author`, writes a SKILL.md, runs `workflowskill_validate`)*
+>
+> Validated — 3 steps: `fetch`, `filter`, `email`. Running a test now... *(invokes `workflowskill_run`)*
+>
+> Run complete: 4 AI stories found, summary drafted. Ready to schedule — want me to set up a daily cron at 8 AM?
+
+## Workflow Lifecycle
+
+```
+describe workflow in natural language
+    ↓
+/workflowskill-author  (agent writes YAML)
+    ↓
+workflowskill_validate  (catch errors early)
+    ↓
+workflowskill_run  (test run, review RunLog)
+    ↓
+workflowskill_runs  (diagnose failures, iterate)
+    ↓
+cron  (schedule for automated execution)
+```
+
+## Repositories
+
+| Repo | Description |
+|------|-------------|
+| [workflowskill](https://github.com/matthew-h-cromer/workflowskill) | Specification and reference runtime |
+| **openclaw-workflowskill** (this repo) | OpenClaw plugin — author, validate, run, and review workflows from the agent |
+
+## Quick Start
+
+Requires [OpenClaw](https://openclaw.ai).
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install openclaw-workflowskill
+```
+
+### 2. Configure Anthropic credentials
+
+The plugin reads your Anthropic API key from OpenClaw's credential store — no `.env` file needed. Make sure an Anthropic auth profile is configured in OpenClaw (`~/.openclaw/agents/main/agent/auth-profiles.json`).
+
+### 3. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Verify
+
+```bash
+openclaw plugins list
+# → workflowskill: 4 tools registered
+
+openclaw skills list
+# → workflowskill-author (user-invocable)
+```
+
+## Tools
+
+Registers four tools with the OpenClaw agent:
+
+| Tool | Description |
+|------|-------------|
+| `workflowskill_validate` | Parse and validate a SKILL.md or raw YAML workflow |
+| `workflowskill_run` | Execute a workflow and return a compact run summary |
+| `workflowskill_runs` | List and inspect past run logs |
+| `workflowskill_llm` | Call Anthropic directly for inline LLM reasoning in workflows |
+
+Also ships the `/workflowskill-author` skill — just say "I want to automate X" and the agent handles the rest: researching, writing, validating, and test-running the workflow in chat.
+
+## Workspace Layout
+
+```
+<workspace>/
+  skills/              # Workflow SKILL.md files (one per subdirectory)
+    daily-triage/
+      SKILL.md
+  workflow-runs/       # RunLog JSON files (auto-created)
+    daily-triage-2024-01-15T09-00-00.000Z.json
+```
+
+## Cron Scheduling
+
+Schedule a workflow to run autonomously via OpenClaw's cron, at `~/.openclaw/cron/jobs.json`:
+
+```json
+{
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Run the daily-triage workflow using workflowskill_run\n\nSend results to Slack in the #general channel",
+    "model": "haiku"
+  }
+}
+```
+
+Always set `"model": "haiku"` — cron runs are lightweight orchestration and don't need a powerful model. Put delivery instructions (e.g. Slack channel) in the cron message, not in the workflow, so workflows stay reusable.
+
+Review past runs via `workflowskill_runs`.
+
+## Architecture
+
+### Tool delegation
+
+Workflow `tool` steps are forwarded to the **OpenClaw gateway** via `POST /tools/invoke`. Any tool registered with the gateway is available to a workflow — the plugin sends the tool name and args as JSON and returns the result. Gateway auth (`config.gateway.auth.token`) must be configured or the plugin will refuse to start.
+
+The `workflowskill_llm` tool is built-in: it calls Anthropic directly using the API key from OpenClaw's credential store, and is always available.
+
+The plugin's own four tools (`workflowskill_validate`, `workflowskill_run`, `workflowskill_runs`, `workflowskill_llm`) are blocked from being forwarded to the gateway to prevent infinite recursion.
+
+## Tool Reference
+
+### `workflowskill_validate`
+
+Parse and validate a SKILL.md or raw YAML workflow.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `content` | string | yes | SKILL.md text or raw workflow YAML |
+
+Returns `{ valid, errors[], name, stepCount, stepTypes[] }`.
+
+### `workflowskill_run`
+
+Execute a workflow and return a compact run summary. The full RunLog is persisted to `workflow-runs/` and retrievable via `workflowskill_runs` with `run_id`.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflow_name` | string | no* | Name of a skill resolved from skills directories |
+| `content` | string | no* | Inline SKILL.md content (bypasses skill files) |
+| `inputs` | object | no | Override workflow input defaults |
+
+*One of `workflow_name` or `content` is required.
+
+### `workflowskill_runs`
+
+List and inspect past run logs.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflow_name` | string | no | Filter by workflow name |
+| `run_id` | string | no | Get full RunLog detail for one run |
+| `status` | string | no | Filter by `"success"` or `"failed"` |
+
+No params → 20 most recent runs (summary view).
+
+### `workflowskill_llm`
+
+Call Anthropic directly and return the text response. Uses the API key from OpenClaw's credential store. Useful in workflow `tool` steps when you need inline LLM reasoning.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | string | yes | The prompt to send to the LLM |
+| `model` | string | no | Model alias (`haiku`, `sonnet`, `opus`) or full model ID — omit to use the default |
+
+Returns `{ text: string }`.
+
+## Development
+
+The plugin imports from `workflowskill` (peer dependency), installed from npm. No build step is required for type checking:
+
+```bash
+npm install
+npm run typecheck
+```
+
+To test changes, link the plugin locally and restart the OpenClaw gateway:
+
+```bash
+openclaw plugins install --link "$(pwd)"
+openclaw gateway restart
+openclaw tools invoke workflowskill_validate '{"content": "..."}'
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,235 @@
+// WorkflowSkill OpenClaw Plugin
+//
+// Entry point called by OpenClaw when the plugin is loaded.
+// Default-exports an object with id + register(api) per the OpenClaw plugin API.
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AUTHORING_SKILL } from 'workflowskill';
+import { validateHandler } from './tools/validate.js';
+import { runHandler } from './tools/run.js';
+import { runsHandler } from './tools/runs.js';
+import { createAdapters, type GatewayConfig } from './lib/adapters.js';
+
+// ─── OpenClaw plugin API types ─────────────────────────────────────────────
+
+/** JSON Schema (subset) for describing tool parameters. */
+interface JsonSchemaObject {
+  type: string;
+  description?: string;
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  items?: JsonSchemaObject;
+  enum?: string[];
+}
+
+/** Content block returned by execute handlers. */
+interface TextContent {
+  type: 'text';
+  text: string;
+}
+
+/** Specification for registering a tool with OpenClaw. */
+interface ToolSpec {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, JsonSchemaObject>;
+    required?: string[];
+  };
+  execute: (_id: unknown, params: Record<string, unknown>) => Promise<{ content: TextContent[] }>;
+}
+
+/** OpenClaw agent config shape (relevant subset). */
+interface OpenClawConfig {
+  agents?: { defaults?: { workspace?: string } };
+  gateway?: {
+    port?: number;
+    bind?: string;
+    auth?: { token?: string; password?: string };
+  };
+}
+
+/** The API object OpenClaw passes to register(). */
+interface PluginApi {
+  /** OpenClaw configuration object. */
+  config: OpenClawConfig;
+  /** Register a tool with the OpenClaw agent. */
+  registerTool(spec: ToolSpec): void;
+}
+
+/** Build a GatewayConfig from the OpenClaw config. Throws if auth is missing. */
+function buildGatewayConfig(config: OpenClawConfig): GatewayConfig {
+  const token = config?.gateway?.auth?.token;
+  if (!token) {
+    throw new Error(
+      'WorkflowSkill plugin requires gateway auth to be configured. ' +
+        'Set config.gateway.auth.token in your OpenClaw configuration.',
+    );
+  }
+  // 'loopback' is an OpenClaw keyword meaning 127.0.0.1 — normalise to localhost.
+  const rawBind = config?.gateway?.bind ?? 'localhost';
+  const bind = rawBind === 'loopback' ? 'localhost' : rawBind;
+  const port = config?.gateway?.port ?? 3000;
+  return { baseUrl: `http://${bind}:${port}`, token };
+}
+
+/** Wrap a handler result as an OpenClaw text content response. */
+function toContent(result: unknown): { content: TextContent[] } {
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+
+// ─── Plugin entry point ────────────────────────────────────────────────────
+
+export default {
+  id: 'workflowskill',
+
+  register(api: PluginApi): void {
+    const workspace = api?.config?.agents?.defaults?.workspace;
+    if (typeof workspace !== 'string' || workspace.length === 0) {
+      throw new Error(
+        `WorkflowSkill plugin requires a valid workspace path in config.agents.defaults.workspace. Received: ${JSON.stringify(workspace)}`,
+      );
+    }
+
+    // Write the canonical authoring skill from the workflowskill package so
+    // resolveSkillContent() finds it at the expected plugin-bundled path.
+    // Append OpenClaw-specific context.
+    const skillDir = join(import.meta.dirname, 'skills', 'workflowskill-author');
+    mkdirSync(skillDir, { recursive: true });
+    const contextPath = join(import.meta.dirname, 'lib', 'openclaw-context.md');
+    const openclawContext = readFileSync(contextPath, 'utf-8')
+      .replace(/\{\{workspace\}\}/g, workspace);
+    writeFileSync(join(skillDir, 'SKILL.md'), AUTHORING_SKILL + '\n' + openclawContext, 'utf-8');
+
+    const gatewayConfig = buildGatewayConfig(api.config);
+    const adapters = createAdapters(gatewayConfig);
+    const { registerTool } = api;
+
+    // ── workflowskill_validate ────────────────────────────────────────────
+    registerTool({
+      name: 'workflowskill_validate',
+      description:
+        'Parse and validate a WorkflowSkill SKILL.md or raw YAML. ' +
+        'Returns { valid, errors[], name, stepCount, stepTypes[] }. ' +
+        'Use before running to catch structural and type errors early.',
+      parameters: {
+        type: 'object',
+        properties: {
+          content: {
+            type: 'string',
+            description: 'Full SKILL.md text or raw workflow YAML to validate.',
+          },
+        },
+        required: ['content'],
+      },
+      execute: async (_id, params) => {
+        return toContent(await validateHandler(params as { content: string }, adapters.toolAdapter));
+      },
+    });
+
+    // ── workflowskill_run ─────────────────────────────────────────────────
+    registerTool({
+      name: 'workflowskill_run',
+      description:
+        'Execute a WorkflowSkill workflow and return a compact run summary. ' +
+        'Accepts a skill_name (resolved from skills directories) or inline content. ' +
+        'The full RunLog is persisted to workflow-runs/ automatically. ' +
+        'Use workflowskill_runs with run_id to retrieve full step-level detail.',
+      parameters: {
+        type: 'object',
+        properties: {
+          workflow_name: {
+            type: 'string',
+            description: 'Name of a workflow skill to resolve from skills directories.',
+          },
+          content: {
+            type: 'string',
+            description: 'Inline SKILL.md content (alternative to workflow_name).',
+          },
+          inputs: {
+            type: 'object',
+            description: 'Input values to override workflow defaults. Optional.',
+          },
+        },
+      },
+      execute: async (_id, params) => {
+        return toContent(
+          await runHandler(
+            params as { workflow_name?: string; content?: string; inputs?: Record<string, unknown> },
+            workspace,
+            adapters,
+          ),
+        );
+      },
+    });
+
+    // ── workflowskill_runs ────────────────────────────────────────────────
+    registerTool({
+      name: 'workflowskill_runs',
+      description:
+        'List and inspect past workflow run logs. ' +
+        'No params → 20 most recent runs (summary). ' +
+        'workflow_name → filter by workflow. ' +
+        'run_id → full RunLog detail. ' +
+        'status → filter by "success" or "failed". ' +
+        'Use for failure diagnosis: find failed run → detail view → explain first failed step.',
+      parameters: {
+        type: 'object',
+        properties: {
+          workflow_name: {
+            type: 'string',
+            description: 'Filter results to a specific workflow by name.',
+          },
+          run_id: {
+            type: 'string',
+            description: 'Get the full RunLog for a specific run ID.',
+          },
+          status: {
+            type: 'string',
+            enum: ['success', 'failed'],
+            description: 'Filter by run status.',
+          },
+        },
+      },
+      execute: async (_id, params) => {
+        return toContent(
+          await runsHandler(
+            params as { workflow_name?: string; run_id?: string; status?: string },
+            workspace,
+          ),
+        );
+      },
+    });
+
+    // ── workflowskill_llm ─────────────────────────────────────────────────────
+    registerTool({
+      name: 'workflowskill_llm',
+      description:
+        'Call Anthropic directly and return the text response. ' +
+        'Uses the API key from OpenClaw\'s credential store (~/.openclaw/agents/main/agent/auth-profiles.json). ' +
+        'Use in workflow tool steps when you need LLM reasoning inline. ' +
+        'model is optional (haiku / sonnet / opus or full model ID); omit for the default.',
+      parameters: {
+        type: 'object',
+        properties: {
+          prompt: {
+            type: 'string',
+            description: 'The prompt to send to the LLM.',
+          },
+          model: {
+            type: 'string',
+            description: 'Model alias or ID. Optional — omit to use the Anthropic default.',
+          },
+        },
+        required: ['prompt'],
+      },
+      execute: async (_id, params) => {
+        const { prompt, model } = params as { prompt: string; model?: string };
+        const result = await adapters.llmAdapter.call(model, prompt);
+        return toContent({ text: result.text });
+      },
+    });
+  },
+};

package/lib/adapters.ts

@@ -0,0 +1,181 @@
+// adapters.ts — host-delegating adapters for the OpenClaw plugin.
+//
+// Tool steps delegate to the Gateway HTTP API via HostToolAdapter (POST /tools/invoke).
+// LLM steps use AnthropicLLMAdapter with the API key read directly from
+// OpenClaw's credential store at ~/.openclaw/agents/main/agent/auth-profiles.json.
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { LLMAdapter, ToolAdapter, ToolDescriptor, ToolResult } from 'workflowskill';
+import { AnthropicLLMAdapter } from 'workflowskill';
+
+export interface GatewayConfig {
+  baseUrl: string;
+  token: string;
+  timeoutMs?: number;
+}
+
+export interface AdapterSet {
+  toolAdapter: ToolAdapter;
+  llmAdapter: LLMAdapter;
+}
+
+// Tools this plugin registers — must not be forwarded to the gateway to prevent infinite recursion.
+const SELF_REFERENCING_TOOLS = new Set([
+  'workflowskill_validate',
+  'workflowskill_run',
+  'workflowskill_runs',
+  'workflowskill_llm',
+]);
+
+/** ToolAdapter that delegates to the Gateway HTTP API via POST /tools/invoke. */
+export class HostToolAdapter implements ToolAdapter {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private readonly timeoutMs: number;
+
+  constructor(config: GatewayConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.token = config.token;
+    this.timeoutMs = config.timeoutMs ?? 30_000;
+  }
+
+  has(toolName: string): boolean {
+    return !SELF_REFERENCING_TOOLS.has(toolName);
+  }
+
+  async invoke(toolName: string, args: Record<string, unknown>): Promise<ToolResult> {
+    if (SELF_REFERENCING_TOOLS.has(toolName)) {
+      return {
+        output: null,
+        error: `Tool '${toolName}' cannot be called from within a workflow (self-referencing).`,
+      };
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(`${this.baseUrl}/tools/invoke`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.token}`,
+        },
+        body: JSON.stringify({ tool: toolName, args }),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (err) {
+      return {
+        output: null,
+        error: `Tool '${toolName}' invocation failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+
+    if (response.status === 200) {
+      const result = (await response.json()) as unknown;
+      return { output: result };
+    }
+    if (response.status === 404) {
+      return { output: null, error: `Tool '${toolName}' not found or blocked by the gateway.` };
+    }
+    if (response.status === 401) {
+      return {
+        output: null,
+        error: `Tool '${toolName}' invocation failed: unauthorized. Check your gateway token.`,
+      };
+    }
+    if (response.status === 429) {
+      return {
+        output: null,
+        error: `Tool '${toolName}' invocation failed: rate limited by gateway.`,
+      };
+    }
+    const body = await response.text().catch(() => '');
+    return {
+      output: null,
+      error: `Tool '${toolName}' invocation failed: HTTP ${response.status}${body ? `: ${body}` : ''}`,
+    };
+  }
+
+  list(): ToolDescriptor[] {
+    return [];
+  }
+}
+
+/**
+ * Read the Anthropic API key from OpenClaw's credential store.
+ * Throws a clear error if the file is missing or has no anthropic profile.
+ */
+function readAnthropicApiKey(): string {
+  const profilesPath = join(homedir(), '.openclaw', 'agents', 'main', 'agent', 'auth-profiles.json');
+  let parsed: {
+    profiles?: Record<string, { provider?: string; key?: string }>;
+    lastGood?: Record<string, string>;
+  };
+  try {
+    parsed = JSON.parse(readFileSync(profilesPath, 'utf-8')) as typeof parsed;
+  } catch (err) {
+    throw new Error(
+      `WorkflowSkill: could not read OpenClaw auth profiles from ${profilesPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const profiles = parsed.profiles ?? {};
+  // Prefer the profile OpenClaw last used successfully for anthropic.
+  const lastGoodName = parsed.lastGood?.['anthropic'];
+  const profile = lastGoodName
+    ? profiles[lastGoodName]
+    : Object.values(profiles).find((p) => p.provider === 'anthropic');
+  if (!profile?.key) {
+    throw new Error(
+      `WorkflowSkill: no anthropic profile found in ${profilesPath}. Add a profile with provider "anthropic" and a key.`,
+    );
+  }
+  return profile.key;
+}
+
+/**
+ * Create host adapters backed by the Gateway HTTP API.
+ *
+ * HostToolAdapter forwards tool steps to the gateway's POST /tools/invoke endpoint.
+ * Self-referencing tools (the plugin's own four tools) are blocked to prevent recursion.
+ * LLM steps use AnthropicLLMAdapter with the key read from OpenClaw's credential store.
+ */
+export function createAdapters(gatewayConfig: GatewayConfig): AdapterSet {
+  const hostTools = new HostToolAdapter(gatewayConfig);
+  const llmAdapter = new AnthropicLLMAdapter(readAnthropicApiKey());
+
+  const LLM_COMPLETE = 'workflowskill_llm';
+  const LLM_COMPLETE_DESCRIPTOR: ToolDescriptor = {
+    name: LLM_COMPLETE,
+    description: 'Call the host LLM with a prompt; returns { text }.',
+  };
+
+  const toolAdapter: ToolAdapter = {
+    has(toolName: string): boolean {
+      if (toolName === LLM_COMPLETE) return true;
+      return hostTools.has(toolName);
+    },
+    async invoke(toolName: string, args: Record<string, unknown>): Promise<ToolResult> {
+      if (toolName === LLM_COMPLETE) {
+        const result = await llmAdapter.call(
+          args.model as string | undefined,
+          args.prompt as string,
+        );
+        return { output: { text: result.text } };
+      }
+      return hostTools.invoke(toolName, args);
+    },
+    list(): ToolDescriptor[] {
+      const hostToolList = hostTools.list();
+      return [
+        LLM_COMPLETE_DESCRIPTOR,
+        ...hostToolList.filter((t) => t.name !== LLM_COMPLETE),
+      ];
+    },
+  };
+
+  return {
+    toolAdapter,
+    llmAdapter,
+  };
+}

package/lib/openclaw-context.md

@@ -0,0 +1,27 @@
+## OpenClaw Integration
+
+### Where to Save Skills
+
+Save authored workflows to:
+
+```
+{{workspace}}/skills/<name>/SKILL.md
+```
+
+### Scheduling Workflows via Cron
+
+OpenClaw schedules cron jobs at `~/.openclaw/cron/jobs.json`.
+
+When a cron triggers, it invokes an agent session. The message should be a short trigger — put delivery instructions (e.g. Slack channel) in the cron, not the workflow, so workflows stay reusable. Do not put business logic in the cron prompt; use `workflowskill_run` to invoke the workflow instead.
+
+Always set `"model": "haiku"` on cron payloads — cron runs are lightweight orchestration and don't need a powerful model.
+
+```json
+{
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Run the <name> workflow using workflowskill_run\n\nSend results to Slack in the #general channel",
+    "model": "haiku"
+  }
+}
+```

package/lib/storage.ts

@@ -0,0 +1,123 @@
+// storage.ts — RunLog file operations and skill resolution for the OpenClaw plugin.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { RunLog } from 'workflowskill';
+
+/** Path to the run-logs directory inside the workspace. */
+export function runsDir(workspace: string): string {
+  return join(workspace, 'workflow-runs');
+}
+
+/**
+ * Resolve a skill's SKILL.md content by name.
+ *
+ * Search order:
+ *   1. <workspace>/skills/<name>/SKILL.md
+ *   2. <plugin-dir>/skills/<name>/SKILL.md  (bundled skills)
+ *
+ * Throws with a descriptive error listing all searched paths if not found.
+ */
+export function resolveSkillContent(workspace: string, name: string): string {
+  const workspacePath = join(workspace, 'skills', name, 'SKILL.md');
+  if (existsSync(workspacePath)) {
+    return readFileSync(workspacePath, 'utf-8');
+  }
+
+  const pluginPath = join(import.meta.dirname, '..', 'skills', name, 'SKILL.md');
+  if (existsSync(pluginPath)) {
+    return readFileSync(pluginPath, 'utf-8');
+  }
+
+  throw new Error(
+    `Skill "${name}" not found. Searched:\n  ${workspacePath}\n  ${pluginPath}`,
+  );
+}
+
+/** Persist a RunLog to <workspace>/workflow-runs/<name>-<timestamp>.json. */
+export function saveRunLog(workspace: string, log: RunLog): string {
+  const dir = runsDir(workspace);
+  mkdirSync(dir, { recursive: true });
+  const safeTimestamp = log.started_at.replace(/:/g, '-');
+  const filename = `${log.workflow}-${safeTimestamp}.json`;
+  const path = join(dir, filename);
+  writeFileSync(path, JSON.stringify(log, null, 2) + '\n', 'utf-8');
+  return path;
+}
+
+export interface RunSummaryEntry {
+  id: string;
+  workflow: string;
+  status: string;
+  started_at: string;
+  duration_ms: number;
+  steps_executed: number;
+  steps_skipped: number;
+  total_tokens: number;
+  error_message?: string;
+}
+
+/** Read all RunLog files and return summary entries, newest first. */
+export function listRuns(
+  workspace: string,
+  filter?: { workflow_name?: string; status?: string },
+): RunSummaryEntry[] {
+  const dir = runsDir(workspace);
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const entries: RunSummaryEntry[] = [];
+  for (const file of files) {
+    try {
+      const raw = readFileSync(join(dir, file), 'utf-8');
+      const log = JSON.parse(raw) as RunLog;
+
+      if (filter?.workflow_name && log.workflow !== filter.workflow_name) continue;
+      if (filter?.status && log.status !== filter.status) continue;
+
+      entries.push({
+        id: log.id,
+        workflow: log.workflow,
+        status: log.status,
+        started_at: log.started_at,
+        duration_ms: log.duration_ms,
+        steps_executed: log.summary.steps_executed,
+        steps_skipped: log.summary.steps_skipped,
+        total_tokens: log.summary.total_tokens,
+        error_message: log.error?.message,
+      });
+    } catch {
+      // Skip corrupt files
+    }
+  }
+
+  // Sort newest first
+  entries.sort((a, b) => b.started_at.localeCompare(a.started_at));
+  return entries;
+}
+
+/** Read a single RunLog by run ID. Returns null if not found. */
+export function getRunLog(workspace: string, runId: string): RunLog | null {
+  const dir = runsDir(workspace);
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return null;
+  }
+
+  for (const file of files) {
+    try {
+      const raw = readFileSync(join(dir, file), 'utf-8');
+      const log = JSON.parse(raw) as RunLog;
+      if (log.id === runId) return log;
+    } catch {
+      // Skip corrupt files
+    }
+  }
+  return null;
+}

package/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "workflowskill",
+  "name": "WorkflowSkill",
+  "description": "Author, validate, run, and review WorkflowSkill YAML workflows",
+  "version": "0.1.0",
+  "skills": ["skills/workflowskill-author"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "openclaw-workflowskill",
+  "version": "0.1.0",
+  "description": "WorkflowSkill plugin for OpenClaw — author, validate, run, and review YAML workflows",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "lib/",
+    "tools/",
+    "openclaw.plugin.json",
+    "LICENSE"
+  ],
+  "keywords": [
+    "openclaw",
+    "workflowskill",
+    "workflow",
+    "automation"
+  ],
+  "license": "MIT",
+  "author": "Matthew Cromer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matthew-h-cromer/openclaw-workflowskill.git"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "workflowskill": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "workflowskill": "^0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "reset": "bash scripts/reset.sh",
+    "prepublishOnly": "tsc --noEmit --project tsconfig.json"
+  }
+}

package/tools/run.ts

@@ -0,0 +1,94 @@
+// workflowskill_run — execute a workflow and return a compact summary.
+//
+// Accepts either a skill_name (resolved from skills directories)
+// or inline content. Persists the full RunLog to <workspace>/workflow-runs/.
+// Returns a compact summary to avoid blowing up the calling agent's context.
+
+import { runWorkflowSkill } from 'workflowskill';
+import type { RunLog, RunSummary } from 'workflowskill';
+import type { AdapterSet } from '../lib/adapters.js';
+import { resolveSkillContent, saveRunLog } from '../lib/storage.js';
+
+export interface RunParams {
+  workflow_name?: string;
+  content?: string;
+  inputs?: Record<string, unknown>;
+}
+
+interface RunSummarySuccess {
+  status: 'success';
+  id: string;
+  workflow: string;
+  duration_ms: number;
+  summary: RunSummary;
+  outputs: Record<string, unknown>;
+}
+
+interface RunSummaryFailed {
+  status: 'failed';
+  id: string;
+  workflow: string;
+  duration_ms: number;
+  summary: RunSummary;
+  error: RunLog['error'];
+  failed_step: {
+    id: string;
+    executor: string;
+    error: string | undefined;
+  } | undefined;
+}
+
+function summarizeRunLog(log: RunLog): RunSummarySuccess | RunSummaryFailed {
+  const base = {
+    id: log.id,
+    workflow: log.workflow,
+    duration_ms: log.duration_ms,
+    summary: log.summary,
+  };
+
+  if (log.status === 'success') {
+    return { status: 'success', ...base, outputs: log.outputs };
+  }
+
+  const failedStep = log.steps.find((s) => s.status === 'failed');
+  return {
+    status: 'failed',
+    ...base,
+    error: log.error,
+    failed_step: failedStep
+      ? { id: failedStep.id, executor: failedStep.executor, error: failedStep.error }
+      : undefined,
+  };
+}
+
+export async function runHandler(
+  params: RunParams,
+  workspace: string,
+  adapters: AdapterSet,
+): Promise<RunSummarySuccess | RunSummaryFailed> {
+  const { workflow_name, content: inlineContent, inputs = {} } = params;
+
+  let content = inlineContent ?? '';
+  if (!content && workflow_name) {
+    content = resolveSkillContent(workspace, workflow_name);
+  }
+
+  const { toolAdapter, llmAdapter } = adapters;
+
+  const log: RunLog = await runWorkflowSkill({
+    content,
+    inputs,
+    toolAdapter,
+    llmAdapter,
+    workflowName: workflow_name ?? 'inline',
+  });
+
+  // Persist full log
+  try {
+    saveRunLog(workspace, log);
+  } catch {
+    // Persistence failure is non-fatal
+  }
+
+  return summarizeRunLog(log);
+}

package/tools/runs.ts

@@ -0,0 +1,40 @@
+// workflowskill_runs — list and inspect past run logs.
+//
+// No params         → list 20 most recent runs (summary view)
+// workflow_name     → filter by workflow name
+// run_id            → get full RunLog detail for one run
+// status            → filter by "success" or "failed"
+
+import type { RunLog } from 'workflowskill';
+import { getRunLog, listRuns, type RunSummaryEntry } from '../lib/storage.js';
+
+export interface RunsParams {
+  workflow_name?: string;
+  run_id?: string;
+  status?: string;
+}
+
+export type RunsResult = RunSummaryEntry[] | RunLog | { error: string };
+
+const RECENT_LIMIT = 20;
+
+export function runsHandler(params: RunsParams, workspace: string): RunsResult {
+  const { workflow_name, run_id, status } = params;
+
+  // Detail view — return full RunLog for a specific run
+  if (run_id) {
+    const log = getRunLog(workspace, run_id);
+    if (!log) {
+      return { error: `No run found with id "${run_id}"` };
+    }
+    return log;
+  }
+
+  // Summary view — list and filter
+  const entries = listRuns(workspace, {
+    workflow_name,
+    status,
+  });
+
+  return entries.slice(0, RECENT_LIMIT);
+}

package/tools/validate.ts

@@ -0,0 +1,20 @@
+// workflowskill_validate — parse and validate SKILL.md or raw YAML.
+
+import { validateWorkflowSkill } from 'workflowskill';
+import type { ToolAdapter } from 'workflowskill';
+
+export interface ValidateParams {
+  content: string;
+}
+
+export interface ValidateResult {
+  valid: boolean;
+  errors: Array<{ path: string; message: string }>;
+  name?: string;
+  stepCount?: number;
+  stepTypes?: string[];
+}
+
+export async function validateHandler(params: ValidateParams, toolAdapter: ToolAdapter): Promise<ValidateResult> {
+  return validateWorkflowSkill({ content: params.content, toolAdapter });
+}