Files

Build apps with the OpenWorker skill

One openworker-harness-builder skill helps Codex and Claude Code build Desktop, Web and Node.js applications with the OpenWorker Harness SDK. It includes version-matched SDK snippets, a scoped file-organizer example, a complete streaming approval loop and separate track references. No OpenWorker checkout is required for the packaged skill, and installing it does not install the SDK or a runtime.

This skill release targets SDK 0.1.0-beta.5, including provider caching, attempt-aware streaming, per-turn session options, and auto-approver/compaction guidance.

Install the skill

From an existing app project, install the latest published skill:

npx @openworkerai/openworker-harness-builder --agent codex --project .

For Claude Code:

npx @openworkerai/openworker-harness-builder --agent claude --project .

These project commands create .agents/skills/openworker-harness-builder/ for Codex or .claude/skills/openworker-harness-builder/ for Claude Code. It supports quoted project paths on Windows and macOS and leaves global settings alone. If a skill already exists, an interactive terminal asks before replacing it and saves the old copy as a backup. references/installation.json records the matching SDK version, without local checkout paths or credentials. Use sdkVersion from that file for the SDK. Skill and SDK package versions may differ; this skill release targets SDK 0.1.0-beta.5.

Across your projects

For user-wide installation, use --global instead of --project:

npx @openworkerai/openworker-harness-builder --agent claude --global
npx @openworkerai/openworker-harness-builder --agent codex --global

This installs into ~/.claude/skills/openworker-harness-builder/ for Claude Code or ~/.agents/skills/openworker-harness-builder/ for Codex, making the skill available across projects for your user on this machine. It does not install into Claude web or Cowork, change account settings, or require npm install -g or administrator access. Choose either --global or --project, not both. Both modes require confirmation or the explicit replacement flag before replacing an existing skill.

Update an existing installation

Run the same install command again. In an interactive terminal it asks:

Replace the existing skill? A backup will be saved. [y/N]

Enter y or yes to replace it. Enter or n leaves it unchanged. For scripts, or to skip the prompt explicitly, use:

npx @openworkerai/openworker-harness-builder --agent claude --global --replace-existing
npx @openworkerai/openworker-harness-builder --agent codex --project . --replace-existing

Non-interactive installs never prompt and require --replace-existing to update. Every replacement saves the complete old directory, including custom files, under .claude/skill-backups/ or .agents/skill-backups/ in the selected project or home. The installer prints the exact backup path. Backups are outside the active skills directory, so coding agents do not load duplicates. A new complete copy replaces the old one; obsolete files are not merged into it. If activation fails, the installer attempts to restore the previous copy and reports its backup location if automatic restoration fails. Review customizations before copying any back.

An interrupted installer can leave an installation lock in .claude/ or .agents/. If the next install reports that lock, first confirm no installer is running, then review and remove the reported lock directory before retrying. Existing backups are never automatically deleted.

Skill and SDK publications are independent: updating this Skill does not replace the README inside an already-installed SDK package. Use the bundled version-matched references for these examples and installation.json for the exact SDK pin.

Unversioned commands select npm's latest release. To pin an installation for reproducibility, append @<version> to the package name. The installer records the compatible SDK version separately; the skill and SDK versions may differ.

The skill is discoverable in the selected scope. Restart the coding-agent session if it does not appear. Invoke $openworker-harness-builder in Codex or /openworker-harness-builder in Claude Code, or ask:

Use the openworker-harness-builder skill to build a desktop app that summarizes a selected code directory. Explain the SDK calls as you build, test the app, and prepare an unpacked desktop package.

For the Web track:

Use the openworker-harness-builder skill to build a web app where I can upload a PDF and ask questions with page references. Explain the agent and session code and test the application locally.

The shared skill includes a Railway deployment track and Docker assets. The default is one Node service serving the frontend and API, with the Rust harness running as a managed child process. The recipe has been tested locally and on Railway with the published SDK, including streamed Claude responses and conversation recovery after redeployment. Vercel recipes and a cluster-operations skill will follow separately. This installer targets local Codex and Claude Code sessions.

Claude workspace uploads

Claude's Customize → Skills → Upload is a separate installation route. For that flow, zip the complete installed openworker-harness-builder directory, including its references, Docker assets and references/installation.json; uploading only SKILL.md loses the supporting files. The npm .tgz package is not this upload format. Uploading a skill provides instructions, not an installed SDK, runtime, or permission to deploy an app. The workspace upload flow has not been qualified by this package's local installer tests.

Try the local candidate

From an OpenWorker checkout, the existing source command remains available:

node skills/install.mjs --agent codex --project /path/to/your-app

Prepare the standalone package without compiling or downloading a native runtime:

node skills/prepare.mjs /absolute/new-skills-candidate

Install the resulting archive into a temporary project or use it through npm exec:

npm exec --package /absolute/new-skills-candidate/archives/openworkerai-openworker-harness-builder-0.1.0-beta.8.tgz -- openworker-harness-builder --agent codex --project /path/to/your-app

The preparer never publishes. Source package manifests remain private; staged candidates remove that marker for the separately reviewed publication step. The Skill's exact openworkerSdkVersion pin is independent of the native-release manifest in a checkout; preserve the SDK version qualified for that Skill release.

Installation locations follow the official Codex skill documentation and Claude Code skill documentation.

Validate source, file scope and packed installation with node --test skills/install.test.mjs skills/package.test.mjs skills/local-script.test.mjs. To include the native approval/resume test, set OW_SKILL_SDK_NODE_MODULES to an absolute consumer node_modules containing the matching published SDK/runtime. That test uses a loopback model fixture and does not spend model tokens.

Railway recipe checks

The Railway reference and Docker assets are installed with the skill. To exercise the container contract locally using a verified SDK artifact manifest:

OW_RAILWAY_CONTAINER_TEST=1 \
OW_SDK_PUBLICATION_MANIFEST=/absolute/path/to/publication-manifest.json \
node --test skills/railway-container.test.mjs

This opt-in test builds a Linux Node image from the bundled Dockerfile, supplies the SDK/runtime archives without a source checkout dependency, and uses a local model fixture. It checks native discovery, the configured port, readiness, unauthorized requests, streamed text, clean shutdown and conversation recovery after replacing the container with the same named volume. It also checks that local secrets and host node_modules are excluded from the image. It cleans up its own containers, volume, network and image. Debian packages may be downloaded during image build; model traffic stays on an isolated Docker network.

This does not qualify live Railway routing, credentials, billing or deployment replacement. Those checks require an authorized Railway target.

A separate live Railway check used SDK 0.1.0-beta.1, the bundled Dockerfile, one replica and a persistent /data volume. It verified HTTPS routing, rejected unauthenticated requests, streamed output before model completion, explicit cancellation, graceful shutdown, unchanged session references after redeployment, and real Anthropic recall of earlier conversation content. This qualifies the single-service recipe; it does not establish multi-replica or zero-downtime behavior.

When upgrading from the earlier openworker-apps skill, review and remove that old skill from the same installation scope after installing the new name. Replacement applies only to openworker-harness-builder; the old-named skill is left untouched.