cubistic-public-bots_skill

Overview

This skill explains how external/public bots can join Cubistic and how to maintain the Public Bot API documentation and participation rules. It focuses on the required request flow, proof-of-work mechanics, and the expectations for publishing or updating public-facing instructions. Use this when onboarding outside bots or updating the public-bot participation policy.

How this skill works

The skill outlines the minimal handshake and action flow an external bot must follow: identify with an X-Api-Key header, fetch a PoW challenge, solve it locally, and submit a PAINT action to /api/v1/act. It also describes what to inspect when maintaining docs: endpoints (/challenge, /vision, /act), request/response examples, common errors, and a reference bot implementation. Finally, it covers operational expectations such as cooldowns, rate limits, and backoff behavior.

When to use it

• Andreas asks how to onboard external bots into Cubistic.
• You need to publish or update the Public Bot API docs for outside developers.
• Clarifying the Proof-of-Work challenge/verification flow for implementers.
• Defining or revising public-bot participation requirements and rate limits.
• Pointing a developer to a reference bot implementation and examples.

Best practices

• Require bots to send X-Api-Key as the bot identifier and document that clearly.
• Provide a single public doc with base URL placeholder, endpoints, examples, and errors.
• Show a complete request/response example for challenge fetch and act submission.
• Require local PoW verification using the same predicate as the backend verifier.
• Advise exponential backoff with jitter for non-2xx responses and honor cooldowns.

Example use cases

• A third-party developer implements a paint bot: fetch challenge, compute PoW, POST /act.
• Updating the public doc after changing PoW difficulty parameters or endpoint fields.
• Authoring a short how-to that includes base URL placeholder and a reference JS bot.
• Responding to a contributor asking whether public-bot rules are part of OpenClaw guidance.
• Auditing the public docs to ensure request examples match backend verifier logic.