openclaw-skill-claude-code 1.0.0

package/.eslintrc.json

@@ -0,0 +1,14 @@
+{
+  "env": {
+    "es2021": true,
+    "node": true
+  },
+  "extends": ["eslint:recommended", "prettier"],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-console": "off"
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Lint
+        run: npm run lint
+        
+      - name: Format Check
+        run: npm run format:check
+        
+      - name: Commitlint
+        if: github.event_name == 'pull_request'
+        uses: wagoid/commitlint-github-action@v5
+
+  release:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit ${1}

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm test

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100
+}

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to openclaw-skill-claude-code
+
+Thank you for your interest in contributing! We want to make this skill the gold standard for robust agentic coding.
+
+## Development Workflow
+
+1.  **Fork & Clone**: Fork the repo and clone it locally.
+2.  **Install Dependencies**: \`npm install\`
+3.  **Branch**: Create a feature branch (\`feat/my-feature\`).
+4.  **Code**: Implement your changes.
+5.  **Commit**: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    *   \`feat: add timeout handling\`
+    *   \`fix: correct pid tracking\`
+    *   \`docs: update readme\`
+6.  **Push & PR**: Push your branch and open a Pull Request.
+
+## Commits
+
+We enforce Conventional Commits via \`commitlint\`. This enables automated semantic versioning and changelog generation.
+
+Types:
+- \`feat\`: A new feature
+- \`fix\`: A bug fix
+- \`docs\`: Documentation only changes
+- \`style\`: Changes that do not affect the meaning of the code (white-space, formatting, etc)
+- \`refactor\`: A code change that neither fixes a bug nor adds a feature
+- \`perf\`: A code change that improves performance
+- \`test\`: Adding missing tests or correcting existing tests
+- \`chore\`: Changes to the build process or auxiliary tools and libraries such as documentation generation
+
+## Release Process
+
+Releases are automated via GitHub Actions and \`semantic-release\`.
+- Merging to \`main\` triggers a release.
+- Version number is determined by commit types (fix=patch, feat=minor, BREAKING CHANGE=major).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noncelogic
+
+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,116 @@
+# Resilient Claude Code Skill
+
+**Persistent, detached coding jobs for OpenClaw.**
+
+Most Claude Code wrappers run `exec('claude ...')`. If your agent turn times out, the gateway restarts, or the API hangs — your coding task dies.
+
+This skill treats coding tasks as **persistent, detached jobs** using the `@anthropic-ai/claude-agent-sdk`.
+
+## Why This Exists
+
+### Decoupled Lifecycle
+Agent turns have timeouts (e.g., 900s). Coding tasks take 20+ minutes. This skill starts a Claude agent process, **detaches it** from the agent session, and returns a `jobId`. The agent checks back later.
+
+### Restart Survival
+If you restart OpenClaw (maintenance, crash, update), child processes usually get killed. This skill spawns processes in a separate process group with PID tracking on disk. On reboot, it **re-acquires running jobs** instead of losing them.
+
+### Rate Limit Intelligence
+Generic wrappers treat any pause as a hang. This skill distinguishes between "Claude is thinking" and "API 429/503", bubbling precise status to the orchestrator.
+
+## Architecture
+
+```
+[ OpenClaw Agent ] -> (SKILL.md instructions) -> [ exec: node scripts/run.mjs ]
+                                                        |
+                                                  (Spawn detached job)
+                                                        |
+                                                  [ Claude Agent SDK ]
+                                                        |
+                                                  (Write state to disk)
+                                                        v
+                                                  [ jobs/<jobId>/ ]
+                                                    ├── meta.json    (status, timestamps, pid)
+                                                    ├── output.log   (streaming output)
+                                                    └── result.json  (final result when done)
+```
+
+1. Agent calls `start` — gets a `jobId` and `pid`.
+2. Agent turn ends. The coding job keeps running.
+3. Agent polls `status` on next turn.
+4. Skill reads process status and log tail from disk.
+5. Returns: `running` | `completed` | `failed` | `killed`.
+
+## Usage
+
+### Start a job
+
+```bash
+node scripts/run.mjs start \
+  --prompt "Read TASK.md and implement. Run tests." \
+  --cwd /path/to/project \
+  --job-id task-137
+```
+
+### Check status
+
+```bash
+node scripts/run.mjs status --job-id task-137
+```
+
+### Get logs
+
+```bash
+node scripts/run.mjs logs --job-id task-137 --tail 50
+```
+
+### Get result
+
+```bash
+node scripts/run.mjs result --job-id task-137
+```
+
+### List all jobs
+
+```bash
+node scripts/run.mjs list
+```
+
+### Kill a job
+
+```bash
+node scripts/run.mjs kill --job-id task-137
+```
+
+## File Structure
+
+```
+openclaw-skill-claude-code/
+├── SKILL.md              # OpenClaw skill instructions
+├── README.md             # Documentation
+├── package.json          # Dependencies
+├── scripts/
+│   ├── run.mjs           # CLI entry point
+│   ├── job-manager.mjs   # Job lifecycle management
+│   └── worker.mjs        # Detached worker process
+└── jobs/                 # Runtime state (gitignored)
+    └── <jobId>/
+        ├── meta.json
+        ├── output.log
+        └── result.json
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | — | Claude API key |
+| `CLAUDE_SKILL_JOBS_DIR` | No | `<skill-dir>/jobs` | Directory for job state |
+| `CLAUDE_SKILL_MODEL` | No | SDK default | Override the model |
+
+## How It Works
+
+**Job Manager** (`scripts/job-manager.mjs`): Manages the job lifecycle — `start`, `status`, `result`, `logs`, `list`, `kill`. Spawns workers as detached processes and tracks them by PID on disk.
+
+**Worker** (`scripts/worker.mjs`): Runs in a detached process. Streams the Claude Agent SDK `query()` iterator, writing output to `output.log` and final results to `result.json`. Handles SIGTERM gracefully and detects rate limits.
+
+**CLI** (`scripts/run.mjs`): Thin command-line wrapper over the job manager. All output is structured JSON.

package/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: claude-code
+description: Run coding tasks as persistent, detached jobs using the Claude Agent SDK. Jobs survive agent timeouts, gateway restarts, and API hangs.
+---
+
+# Claude Code Skill
+
+This skill runs coding tasks as **persistent, detached jobs** using the `@anthropic-ai/claude-agent-sdk`. Unlike raw `exec claude` calls, jobs survive agent turn timeouts, gateway restarts, and API rate limits.
+
+## Starting a coding task
+
+Use `exec` to start a detached job. It returns immediately with a `jobId`.
+
+```bash
+node {{skill_dir}}/scripts/run.mjs start \
+  --prompt "Read TASK.md and implement. Run tests." \
+  --cwd /path/to/project \
+  --job-id task-137
+```
+
+**Arguments:**
+- `--prompt` (required): The task description for Claude.
+- `--cwd` (required): The working directory for the coding task.
+- `--job-id` (required): A unique identifier for this job.
+- `--model` (optional): Override the model (defaults to SDK default).
+
+**Returns JSON:**
+```json
+{ "jobId": "task-137", "pid": 12345, "status": "running" }
+```
+
+## Checking status
+
+Poll job status to see if it's still running, completed, or failed.
+
+```bash
+node {{skill_dir}}/scripts/run.mjs status --job-id task-137
+```
+
+**Returns JSON:**
+```json
+{
+  "jobId": "task-137",
+  "pid": 12345,
+  "status": "running",
+  "startedAt": "2025-01-01T00:00:00.000Z",
+  "endedAt": null,
+  "error": null,
+  "rateLimited": false
+}
+```
+
+**Status values:** `running`, `completed`, `failed`, `killed`, `not_found`
+
+If `rateLimited` is `true`, the job hit API rate limits — this is a temporary condition, not a hang.
+
+## Getting logs
+
+Read the last N lines of streaming output from the job.
+
+```bash
+node {{skill_dir}}/scripts/run.mjs logs --job-id task-137 --tail 50
+```
+
+## Getting the result
+
+Once status is `completed`, retrieve the final result.
+
+```bash
+node {{skill_dir}}/scripts/run.mjs result --job-id task-137
+```
+
+**Returns JSON:**
+```json
+{
+  "jobId": "task-137",
+  "status": "completed",
+  "result": "...",
+  "cost_usd": 0.05,
+  "duration_ms": 120000,
+  "num_turns": 8
+}
+```
+
+## Listing all jobs
+
+```bash
+node {{skill_dir}}/scripts/run.mjs list
+```
+
+## Killing a job
+
+```bash
+node {{skill_dir}}/scripts/run.mjs kill --job-id task-137
+```
+
+## Best Practices
+
+- **Unique job IDs**: Use descriptive IDs like `issue-42` or `feat-auth-v2` to track jobs.
+- **Poll status**: After starting a job, check status periodically. Jobs can take 5-30 minutes.
+- **Check logs on failure**: If status is `failed`, read logs to understand what went wrong.
+- **Rate limits are normal**: If `rateLimited` is true, the SDK is handling retries automatically.
+- **Verification**: Include "Run tests" in your prompt to have Claude verify its own changes.
+
+## Environment
+
+- `ANTHROPIC_API_KEY` — required (the skill checks for this and fails fast with a clear error if missing).
+- `CLAUDE_SKILL_JOBS_DIR` — optional, defaults to `<skill_dir>/jobs`.
+- `CLAUDE_SKILL_MODEL` — optional, overrides the default model.

package/TASK.md

@@ -0,0 +1,178 @@
+# TASK: Build Resilient Claude Code Skill for OpenClaw (#1)
+
+## Context
+This is an OpenClaw skill that wraps the `@anthropic-ai/claude-agent-sdk` (the official Claude Agent SDK) to run coding tasks as persistent, detached jobs. The current method (`exec claude --dangerously-skip-permissions`) is fragile — jobs die on gateway restart, timeouts, or API hangs.
+
+## Architecture
+
+```
+[ OpenClaw Agent ] -> (SKILL.md instructions) -> [ exec: node scripts/run.mjs ]
+                                                        |
+                                                  (Spawn detached job)
+                                                        |
+                                                  [ Claude Agent SDK ]
+                                                        |
+                                                  (Write state to disk)
+                                                        v
+                                                  [ jobs/<jobId>/ ]
+                                                    ├── meta.json    (status, timestamps, pid)
+                                                    ├── output.log   (streaming output)
+                                                    └── result.json  (final result when done)
+```
+
+## SDK Reference
+
+The official SDK is `@anthropic-ai/claude-agent-sdk` (v0.2.42). TypeScript usage:
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Fix the bug in auth.py",
+  options: {
+    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"],
+    permissionMode: "acceptEdits", // Auto-approve file edits
+  }
+})) {
+  if (message.type === "assistant" && message.message?.content) {
+    for (const block of message.message.content) {
+      if ("text" in block) console.log(block.text);
+      else if ("name" in block) console.log(`Tool: ${block.name}`);
+    }
+  } else if (message.type === "result") {
+    console.log(`Done: ${message.subtype}`);
+  }
+}
+```
+
+Auth: Set `ANTHROPIC_API_KEY` env var. The SDK reads it automatically.
+
+Available tools: `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebSearch`, `WebFetch`.
+
+## Implementation
+
+### 1. Package Setup
+Create `package.json` with dependencies:
+- `@anthropic-ai/claude-agent-sdk`
+- No other runtime deps needed
+
+### 2. Job Manager (`scripts/job-manager.mjs`)
+Core module that manages job lifecycle:
+
+```javascript
+// start(jobId, prompt, cwd, options) → spawns detached process
+// status(jobId) → reads meta.json, checks if PID alive
+// result(jobId) → reads result.json
+// logs(jobId, tail) → reads last N lines of output.log
+// list() → lists all jobs with status
+// kill(jobId) → sends SIGTERM to PID
+```
+
+**State directory**: `jobs/<jobId>/`
+- `meta.json`: `{ jobId, pid, status, prompt, cwd, startedAt, endedAt, error }`
+- `output.log`: Streaming text output from the agent
+- `result.json`: Final result text (written on completion)
+
+**Detached spawn**: The job manager spawns `node scripts/worker.mjs <jobId>` as a detached child process (`{ detached: true, stdio: 'ignore' }`) and immediately unrefs it. The worker runs independently.
+
+**PID tracking**: On startup, `status()` checks if the PID in `meta.json` is still alive (`process.kill(pid, 0)`). If the process died without updating status, mark as `failed`.
+
+### 3. Worker (`scripts/worker.mjs`)
+Runs in a detached process. Receives `jobId` as argv:
+
+1. Read `jobs/<jobId>/meta.json` for prompt and cwd
+2. `process.chdir(cwd)`
+3. Stream `query()` from the Agent SDK
+4. Write each message to `output.log` (append)
+5. On completion: write `result.json`, update `meta.json` status to `completed`
+6. On error: update `meta.json` status to `failed`, write error details
+7. Handle SIGTERM gracefully
+
+**Rate limit detection**: Watch for 429/503 patterns in error messages. Set a `rateLimited` flag in `meta.json` so the orchestrator knows it's not a hang.
+
+### 4. CLI Entry Points (`scripts/run.mjs`)
+Simple CLI wrappers for the job manager:
+
+```bash
+# Start a job
+node scripts/run.mjs start --prompt "Fix the bug" --cwd /path/to/project --job-id my-job
+
+# Check status
+node scripts/run.mjs status --job-id my-job
+
+# Get logs (last 50 lines)
+node scripts/run.mjs logs --job-id my-job --tail 50
+
+# Get result
+node scripts/run.mjs result --job-id my-job
+
+# List all jobs
+node scripts/run.mjs list
+
+# Kill a job
+node scripts/run.mjs kill --job-id my-job
+```
+
+Return JSON to stdout for structured output.
+
+### 5. SKILL.md
+Update the skill instructions to use the new scripts instead of raw `exec claude`:
+
+```markdown
+## Starting a coding task
+Use `exec` to run:
+\`\`\`bash
+node /path/to/skill/scripts/run.mjs start \
+  --prompt "Read TASK.md and implement. Run tests." \
+  --cwd /path/to/project \
+  --job-id task-137
+\`\`\`
+
+## Checking status
+\`\`\`bash
+node /path/to/skill/scripts/run.mjs status --job-id task-137
+\`\`\`
+
+## Getting results
+\`\`\`bash
+node /path/to/skill/scripts/run.mjs result --job-id task-137
+\`\`\`
+```
+
+### 6. README.md
+Update with architecture diagram, usage examples, and configuration.
+
+## Configuration
+
+The skill reads these env vars:
+- `ANTHROPIC_API_KEY` — required (Claude API key)
+- `CLAUDE_SKILL_JOBS_DIR` — optional, defaults to `<skill-dir>/jobs`
+- `CLAUDE_SKILL_MODEL` — optional, defaults to SDK default
+
+## File Structure
+```
+openclaw-skill-claude-code/
+├── SKILL.md              # OpenClaw skill instructions
+├── README.md             # Documentation
+├── package.json          # Dependencies
+├── scripts/
+│   ├── run.mjs           # CLI entry point
+│   ├── job-manager.mjs   # Job lifecycle management
+│   └── worker.mjs        # Detached worker process
+└── jobs/                 # Runtime state (gitignored)
+    └── <jobId>/
+        ├── meta.json
+        ├── output.log
+        └── result.json
+```
+
+## Verification
+- `npm install` succeeds
+- `node scripts/run.mjs start --prompt "What files are here?" --cwd . --job-id test-1` starts a job
+- `node scripts/run.mjs status --job-id test-1` shows status
+- `node scripts/run.mjs list` shows all jobs
+- Job survives if parent process exits
+- Handles missing ANTHROPIC_API_KEY gracefully (clear error message)
+
+## Branch
+`feat/1-resilient-job-manager`

package/commitlint.config.js

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "openclaw-skill-claude-code",
+  "version": "1.0.0",
+  "description": "Resilient Claude Code skill for OpenClaw — persistent, detached coding jobs",
+  "type": "module",
+  "scripts": {
+    "start": "node scripts/run.mjs",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.42"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.1",
+    "semantic-release": "^25.0.3"
+  }
+}

package/scripts/job-manager.mjs

@@ -0,0 +1,174 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = join(__dirname, "..");
+const JOBS_DIR = process.env.CLAUDE_SKILL_JOBS_DIR || join(SKILL_DIR, "jobs");
+
+async function ensureJobDir(jobId) {
+  const dir = join(JOBS_DIR, jobId);
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+function metaPath(jobId) {
+  return join(JOBS_DIR, jobId, "meta.json");
+}
+
+function outputPath(jobId) {
+  return join(JOBS_DIR, jobId, "output.log");
+}
+
+function resultPath(jobId) {
+  return join(JOBS_DIR, jobId, "result.json");
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(path) {
+  const data = await readFile(path, "utf-8");
+  return JSON.parse(data);
+}
+
+async function writeJson(path, data) {
+  await writeFile(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+export async function start(jobId, prompt, cwd, options = {}) {
+  const dir = await ensureJobDir(jobId);
+
+  const meta = {
+    jobId,
+    pid: null,
+    status: "starting",
+    prompt,
+    cwd,
+    model: options.model || process.env.CLAUDE_SKILL_MODEL || undefined,
+    allowedTools: options.allowedTools || undefined,
+    startedAt: new Date().toISOString(),
+    endedAt: null,
+    error: null,
+    rateLimited: false,
+  };
+
+  await writeJson(metaPath(jobId), meta);
+  await writeFile(outputPath(jobId), "");
+
+  const workerPath = join(__dirname, "worker.mjs");
+  const child = spawn("node", [workerPath, jobId], {
+    detached: true,
+    stdio: "ignore",
+    cwd: SKILL_DIR,
+    env: { ...process.env },
+  });
+
+  child.unref();
+
+  meta.pid = child.pid;
+  meta.status = "running";
+  await writeJson(metaPath(jobId), meta);
+
+  return { jobId, pid: child.pid, status: "running" };
+}
+
+export async function status(jobId) {
+  let meta;
+  try {
+    meta = await readJson(metaPath(jobId));
+  } catch {
+    return { jobId, status: "not_found" };
+  }
+
+  if (meta.status === "running" && meta.pid) {
+    if (!isPidAlive(meta.pid)) {
+      meta.status = "failed";
+      meta.error = "Process exited unexpectedly";
+      meta.endedAt = new Date().toISOString();
+      await writeJson(metaPath(jobId), meta);
+    }
+  }
+
+  return {
+    jobId: meta.jobId,
+    pid: meta.pid,
+    status: meta.status,
+    startedAt: meta.startedAt,
+    endedAt: meta.endedAt,
+    error: meta.error,
+    rateLimited: meta.rateLimited,
+  };
+}
+
+export async function result(jobId) {
+  try {
+    return await readJson(resultPath(jobId));
+  } catch {
+    const s = await status(jobId);
+    return { jobId, status: s.status, result: null };
+  }
+}
+
+export async function logs(jobId, tail = 50) {
+  try {
+    const content = await readFile(outputPath(jobId), "utf-8");
+    const lines = content.split("\n");
+    const sliced = lines.slice(-tail).join("\n");
+    return { jobId, lines: lines.length, tail: sliced };
+  } catch {
+    return { jobId, lines: 0, tail: "" };
+  }
+}
+
+export async function list() {
+  let entries;
+  try {
+    entries = await readdir(JOBS_DIR, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const jobs = [];
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const s = await status(entry.name);
+      jobs.push(s);
+    }
+  }
+  return jobs;
+}
+
+export async function kill(jobId) {
+  let meta;
+  try {
+    meta = await readJson(metaPath(jobId));
+  } catch {
+    return { jobId, killed: false, error: "Job not found" };
+  }
+
+  if (!meta.pid) {
+    return { jobId, killed: false, error: "No PID recorded" };
+  }
+
+  if (!isPidAlive(meta.pid)) {
+    return { jobId, killed: false, error: "Process already dead" };
+  }
+
+  try {
+    process.kill(meta.pid, "SIGTERM");
+    meta.status = "killed";
+    meta.endedAt = new Date().toISOString();
+    await writeJson(metaPath(jobId), meta);
+    return { jobId, killed: true };
+  } catch (err) {
+    return { jobId, killed: false, error: err.message };
+  }
+}

package/scripts/run.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { start, status, result, logs, list, kill } from "./job-manager.mjs";
+
+function parseArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const key = args[i].slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("--")) {
+        parsed[key] = next;
+        i++;
+      } else {
+        parsed[key] = true;
+      }
+    }
+  }
+  return parsed;
+}
+
+function output(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+function die(message) {
+  output({ error: message });
+  process.exit(1);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const args = parseArgs(rest);
+
+switch (command) {
+  case "start": {
+    const prompt = args.prompt;
+    const cwd = args.cwd || process.cwd();
+    const jobId = args["job-id"];
+
+    if (!prompt) die("--prompt is required");
+    if (!jobId) die("--job-id is required");
+
+    const options = {};
+    if (args.model) options.model = args.model;
+
+    const res = await start(jobId, prompt, cwd, options);
+    output(res);
+    break;
+  }
+
+  case "status": {
+    const jobId = args["job-id"];
+    if (!jobId) die("--job-id is required");
+    output(await status(jobId));
+    break;
+  }
+
+  case "result": {
+    const jobId = args["job-id"];
+    if (!jobId) die("--job-id is required");
+    output(await result(jobId));
+    break;
+  }
+
+  case "logs": {
+    const jobId = args["job-id"];
+    if (!jobId) die("--job-id is required");
+    const tail = parseInt(args.tail, 10) || 50;
+    output(await logs(jobId, tail));
+    break;
+  }
+
+  case "list": {
+    output(await list());
+    break;
+  }
+
+  case "kill": {
+    const jobId = args["job-id"];
+    if (!jobId) die("--job-id is required");
+    output(await kill(jobId));
+    break;
+  }
+
+  default:
+    die(
+      `Unknown command: ${command || "(none)"}. ` +
+      `Available: start, status, result, logs, list, kill`
+    );
+}

package/scripts/worker.mjs

@@ -0,0 +1,183 @@
+import { readFile, writeFile, appendFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_DIR = join(__dirname, "..");
+const JOBS_DIR = process.env.CLAUDE_SKILL_JOBS_DIR || join(SKILL_DIR, "jobs");
+
+const jobId = process.argv[2];
+if (!jobId) {
+  console.error("Usage: node worker.mjs <jobId>");
+  process.exit(1);
+}
+
+const metaFile = join(JOBS_DIR, jobId, "meta.json");
+const outputFile = join(JOBS_DIR, jobId, "output.log");
+const resultFile = join(JOBS_DIR, jobId, "result.json");
+
+async function readMeta() {
+  return JSON.parse(await readFile(metaFile, "utf-8"));
+}
+
+async function writeMeta(meta) {
+  await writeFile(metaFile, JSON.stringify(meta, null, 2) + "\n");
+}
+
+async function log(text) {
+  await appendFile(outputFile, text + "\n");
+}
+
+let shuttingDown = false;
+
+process.on("SIGTERM", async () => {
+  shuttingDown = true;
+  await log("[worker] Received SIGTERM, shutting down gracefully...");
+  const meta = await readMeta();
+  meta.status = "killed";
+  meta.endedAt = new Date().toISOString();
+  await writeMeta(meta);
+  process.exit(0);
+});
+
+async function run() {
+  const meta = await readMeta();
+
+  if (!process.env.ANTHROPIC_API_KEY) {
+    meta.status = "failed";
+    meta.error = "ANTHROPIC_API_KEY environment variable is not set";
+    meta.endedAt = new Date().toISOString();
+    await writeMeta(meta);
+    await log("[worker] ERROR: ANTHROPIC_API_KEY not set");
+    process.exit(1);
+  }
+
+  await log(`[worker] Starting job ${jobId}`);
+  await log(`[worker] Prompt: ${meta.prompt}`);
+  await log(`[worker] CWD: ${meta.cwd}`);
+
+  let queryFn;
+  try {
+    const sdk = await import("@anthropic-ai/claude-agent-sdk");
+    queryFn = sdk.query;
+  } catch (err) {
+    meta.status = "failed";
+    meta.error = `Failed to load SDK: ${err.message}`;
+    meta.endedAt = new Date().toISOString();
+    await writeMeta(meta);
+    await log(`[worker] ERROR: ${meta.error}`);
+    process.exit(1);
+  }
+
+  const options = {
+    cwd: meta.cwd,
+    permissionMode: "bypassPermissions",
+    allowDangerouslySkipPermissions: true,
+  };
+
+  if (meta.model) {
+    options.model = meta.model;
+  }
+
+  if (meta.allowedTools) {
+    options.allowedTools = meta.allowedTools;
+  }
+
+  let resultText = "";
+
+  try {
+    const q = queryFn({ prompt: meta.prompt, options });
+
+    for await (const message of q) {
+      if (shuttingDown) break;
+
+      if (message.type === "assistant" && message.message?.content) {
+        for (const block of message.message.content) {
+          if ("text" in block) {
+            await log(block.text);
+            resultText += block.text + "\n";
+          } else if ("name" in block) {
+            await log(`[tool] ${block.name}`);
+          }
+        }
+      } else if (message.type === "result") {
+        if (message.subtype === "success") {
+          await log(`[worker] Completed successfully`);
+          resultText = message.result || resultText;
+
+          const resultData = {
+            jobId,
+            status: "completed",
+            result: resultText,
+            cost_usd: message.total_cost_usd,
+            duration_ms: message.duration_ms,
+            num_turns: message.num_turns,
+          };
+          await writeFile(resultFile, JSON.stringify(resultData, null, 2) + "\n");
+
+          meta.status = "completed";
+          meta.endedAt = new Date().toISOString();
+          await writeMeta(meta);
+        } else {
+          const errorMsg = message.errors?.join("; ") || message.subtype;
+          await log(`[worker] Error: ${errorMsg}`);
+
+          meta.status = "failed";
+          meta.error = errorMsg;
+          meta.endedAt = new Date().toISOString();
+          await writeMeta(meta);
+
+          const resultData = {
+            jobId,
+            status: "failed",
+            error: errorMsg,
+            result: resultText || null,
+            cost_usd: message.total_cost_usd,
+            duration_ms: message.duration_ms,
+          };
+          await writeFile(resultFile, JSON.stringify(resultData, null, 2) + "\n");
+        }
+      } else if (message.type === "assistant" && message.error) {
+        const errType = message.error;
+        if (errType === "rate_limit") {
+          meta.rateLimited = true;
+          await writeMeta(meta);
+          await log("[worker] Rate limited, SDK will retry...");
+        }
+      }
+    }
+  } catch (err) {
+    const errMsg = err.message || String(err);
+    await log(`[worker] Fatal error: ${errMsg}`);
+
+    const isRateLimit = /429|rate.limit|503|overloaded/i.test(errMsg);
+    meta.status = "failed";
+    meta.error = errMsg;
+    meta.rateLimited = isRateLimit;
+    meta.endedAt = new Date().toISOString();
+    await writeMeta(meta);
+
+    const resultData = {
+      jobId,
+      status: "failed",
+      error: errMsg,
+      result: resultText || null,
+    };
+    await writeFile(resultFile, JSON.stringify(resultData, null, 2) + "\n");
+    process.exit(1);
+  }
+}
+
+run().catch(async (err) => {
+  try {
+    const meta = await readMeta();
+    meta.status = "failed";
+    meta.error = err.message || String(err);
+    meta.endedAt = new Date().toISOString();
+    await writeMeta(meta);
+    await log(`[worker] Unhandled error: ${meta.error}`);
+  } catch {
+    // Can't even write meta, just exit
+  }
+  process.exit(1);
+});