Skip to content
Get packs

Guide · Agent skill

How to use the ClawHub Production Release agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The clawhub-production-release skill is a step-by-step operating manual that teaches an AI agent how to ship ClawHub, the openclaw project's app and command-line tool, to production. It is written for maintainers of the openclaw/clawhub repository and release engineers who want a repeatable, auditable release process. After this guide you will know what the skill does, how to install it, how to trigger it with plain requests, and what it needs before it can run.

ClawHub Production Releaseopenclaw/clawhub · MIT

Quick start

  1. 1Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ directory, or upload it under Settings, then Capabilities, then Skills.
  2. 2Check your tools and access. Make sure the GitHub CLI (gh) is authenticated with permission to dispatch workflows in openclaw/clawhub and that you have access to the Production and npm-release environments.
  3. 3Confirm the commit on main. Ask the agent to confirm the selected commit is on origin/main and record its SHA. Re-check this immediately before any dispatch.
  4. 4Verify the Test deployment. The agent looks for a successful Deploy Test run for that exact SHA and stops if none exists.
  5. 5Dispatch and verify. Dispatch one deploy target or the CLI preflight and publish steps, then confirm the run used the expected SHA and check the live surface on clawhub.ai or the npm version.

What the skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for a task. This one covers two jobs: deploying backend or frontend changes to clawhub.ai, and publishing a stable ClawHub CLI release to npm.

The skill tells the agent to confirm the right commit is on main, dispatch the correct GitHub Actions workflow with the right options, and then prove the result. Proof means recording the workflow URLs, the exact deployed commit SHA, and a live check on clawhub.ai rather than trusting a green run alone.

  • App deploys use the Deploy workflow in .github/workflows/deploy.yml.
  • CLI releases use the workflow in .github/workflows/clawhub-cli-npm-release.yml.
  • Merging to main never deploys the app or publishes the CLI on its own.

Install the clawhub-production-release skill

Download the ZIP for this skill from this page and unzip it. You can place the folder in your personal skills directory, ~/.claude/skills/, so it is available across your projects. Alternatively, put it in a project's .claude/skills/ directory so it applies only to that project.

If you use the Claude apps instead, upload the skill under Settings, then Capabilities, then Skills. Either way, the folder should contain SKILL.md, which is the file the agent reads, plus agents/openai.yaml.

  • Personal install: ~/.claude/skills/clawhub-production-release/
  • Project install: .claude/skills/clawhub-production-release/ inside your project
  • Claude apps: Settings, then Capabilities, then Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it, so you can ask in ordinary language. Requests that match its description include deploying backend or frontend changes to clawhub.ai, dispatching the Deploy workflow, publishing a stable CLI tag, checking release prerequisites, and proving the exact production SHA and workflow outcome.

Be explicit about the action. The skill is designed so that production actions run only when you clearly ask for that release action. A question such as 'what would it take to deploy the frontend?' is a request for checks, not a deploy.

  • 'Check the release prerequisites for a frontend production deploy from main.'
  • 'Dispatch the full production deploy from main and report the workflow URL and deployed SHA.'
  • 'Run the preflight for the stable CLI tag vX.Y.Z and tell me the run ID.'
  • 'Publish the CLI tag I just pushed to npm after the preflight passes.'

Run an app production deploy safely

Before dispatching, the skill requires a successful Deploy Test workflow for the exact main SHA. The agent looks for it with the command below and stops if no successful exact-SHA Test run exists. The skill notes this is an operator check until the production workflow enforces the gate directly.

The deploy is dispatched with one target: full, backend, or frontend. Full deploys Convex, waits for the matching Vercel production deployment, and runs production smoke checks. Backend deploys Convex and runs production HTTP smoke checks. Frontend waits for Vercel's production deployment for the selected main SHA and runs HTTP and UI smoke checks; the workflow does not call vercel deploy. Keep allow_deleting_large_indexes set to false unless you have reviewed the Convex index deletion and explicitly accepted it.

  • Use the GitHub Production environment; backend deploys need the CONVEX_DEPLOY_KEY environment secret.
  • Report the Test workflow URL, production workflow URL, deployed SHA, target, and live proof.
gh run list \n --repo openclaw/clawhub \n --workflow deploy-test.yml \n --branch main \n --commit <MAIN_SHA> \n --status success \n --limit 1 gh workflow run deploy.yml \n --repo openclaw/clawhub \n --ref main \n -f target=full \n -f allow_deleting_large_indexes=false

Publish a stable CLI release to npm

Stable CLI tags must use the form vX.Y.Z. The skill runs a validation-only preflight first, then promotes that exact preflight artifact in the real publish. This means the code you publish is the code that passed preflight.

Real publishes use npm trusted publishing through the npm-release GitHub environment. The trusted publisher must match the repository openclaw/clawhub, the workflow clawhub-cli-npm-release.yml, and the environment npm-release. The agent should verify the published version from npm when the run finishes.

  • Confirm the tag points to the intended commit on main before starting.
  • Record the preflight run ID and URL, then pass that run ID to the publish step.
  • Report the preflight URL, publish URL, tag, release SHA, and published version.
gh workflow run clawhub-cli-npm-release.yml \n --repo openclaw/clawhub \n --ref main \n -f tag=vX.Y.Z \n -f preflight_only=true gh workflow run clawhub-cli-npm-release.yml \n --repo openclaw/clawhub \n --ref main \n -f tag=vX.Y.Z \n -f preflight_only=false \n -f preflight_run_id=<RUN_ID>

Know the requirements and safety limits

The skill needs the GitHub CLI (gh), authenticated with permission to dispatch workflows in openclaw/clawhub. You also need access to the GitHub Production and npm-release environments. Backend deploys require the CONVEX_DEPLOY_KEY environment secret. The optional PLAYWRIGHT_AUTH_STORAGE_STATE_JSON secret enables authenticated UI smoke tests.

The skill uses the network, because it calls GitHub and checks the live site at clawhub.ai. It does not ship scripts of its own. Its rules forbid adding one-off migrations or repairs to the deploy workflow. Data changes must run separately using the related skills clawhub-convex and create-and-cleanup-migration.

  • Requires: authenticated gh CLI, Production and npm-release environment access, CONVEX_DEPLOY_KEY for backend deploys.
  • Optional: PLAYWRIGHT_AUTH_STORAGE_STATE_JSON for authenticated UI smoke tests.
  • Related skills: clawhub-convex and create-and-cleanup-migration.
  • Runs scripts: no. Uses network: yes.

Tips for a smooth release

Re-read the workflow and the exact main SHA immediately before each dispatch, because main can move between your check and your run. Keep the workflow URLs and SHAs in your release notes so the release can be audited later.

Treat a green workflow as the start of verification, not the end. Check the affected route, API, or backend contract on clawhub.ai before reporting success.

  • Run the required validation for the changed surface before dispatching.
  • Use the frontend target when only the web app changed and the backend is unaffected.
  • Stop and fix or rerun Test if the exact-SHA check fails.

What people use it for

  • Shipping a backend change to clawhub.ai with the backend target after the exact-SHA Test run passes.
  • Deploying only a frontend fix using the frontend target, which waits for Vercel's production deployment rather than calling vercel deploy.
  • Running a stable CLI preflight for a vX.Y.Z tag, then publishing that same artifact to npm.
  • Producing a release report with the Test URL, production URL, deployed SHA, target, and live proof.

Frequently asked questions

Is the clawhub-production-release skill free to use?

The skill is published under the MIT licence, as stated on this page. Check the licence file in the openclaw/clawhub repository for the full terms before reusing it.

What do I need before I can use this skill?

You need the GitHub CLI authenticated with permission to dispatch workflows in openclaw/clawhub, access to the GitHub Production and npm-release environments, and the CONVEX_DEPLOY_KEY secret for backend deploys. The workflow names and secrets are specific to that repository.

Can I use this skill for my own project?

Not as written. The workflows, secrets and environments are specific to openclaw/clawhub and will not exist in other repositories. You can use it as a reference for structuring your own release checklist.

Will merging to main deploy my changes automatically?

No. The skill states that ClawHub production changes are manual-only and that merging to main does not deploy the app or publish the CLI. A production action runs only when someone explicitly asks for it.

How do I troubleshoot a deploy that the agent refuses to start?

The most common cause is the safety gate: the agent stops if there is no successful Deploy Test run for the exact main SHA. Rerun Test for that commit, then ask the agent to check again. A missing CONVEX_DEPLOY_KEY secret will also block backend deploys.

Is this skill safe to run unattended?

No. It is designed for a human to authorise each production action. Dispatching a deploy with the wrong target or deleting large Convex indexes can affect the live site, so keep allow_deleting_large_indexes set to false unless you have reviewed the change.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits maintainers of the openclaw/clawhub repository and release engineers who want an agent to follow a strict, auditable release checklist with a human approving each production step. If you are not working on ClawHub, or you want unattended automation, pick a release process built for your own repository and approval workflow instead.

Download the skill