How to use the External Bot Integration Builder agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions that a compatible AI agent can load when a task matches the skill's description. This one, named create-external-bot-integration, covers building and qualifying external bots such as Dot in Paperclip. Its scope includes two-way work, invitations, identity, wakeup, Runner lifecycle, native tools, recovery, and Cloud delivery.

The skill is a process guide rather than a tool that acts on its own. It walks the agent through defining release goals, proving the provider connection, reusing Paperclip's existing execution runner, designing a watched onboarding flow, and checking the result with specific tests and deployment checks.

Install the skill from the ZIP or the Claude apps

Download the ZIP from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder instead.

If you use the Claude apps, you can upload the skill instead. Open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Know what you need before you start

The skill assumes you already have a few things in place. It is written for building integrations, so you need working access to the systems on both sides of the connection.

• A Paperclip repository checkout. The references depend on its internal code, PRs and runner artifacts, so the skill is not useful without it.
• Access to the external bot provider's account and its official API documentation.
• A stable public HTTPS endpoint for testing, as the workflow requires.

Trigger the skill with a natural request

You do not need a special command. Describe the job in plain language, and the agent should match it to the skill's description. The description covers building and qualifying external bots, including two-way work, invitations, identity, wakeup, Runner lifecycle, native tools, recovery, and Cloud delivery.

Good requests name the bot and the outcome you want. Mention the bot's name, whether Paperclip should assign it work, and whether it should start work on its own. The skill will then ask only about consequential unknowns instead of repeating what you already said.

• Build an external bot integration for Dot so Paperclip can assign it work and Dot can start governed work from its own chat.
• Help me qualify our external bot integration. I need tests for reconnection, recovery and cleanup.
• Walk me through the onboarding flow for connecting an external bot, with checks at each stage.

Follow the workflow the skill sets out

The skill is organised into six stages. It starts by setting a release contract that records the target environment, the acting identity, capabilities, and a checkable finish line. It then requires you to prove the uncertain provider boundary first, using a synthetic company and a stable public HTTPS endpoint.

Next, the skill directs you to reuse the existing Runner infrastructure, build onboarding as a watched and resumable workflow, and qualify both correctness and the ordinary user experience. The final stage covers delivering one identifiable candidate and verifying the deployed path.

• Release contract: define the finish line before narrowing the implementation.
• Provider proof: test authentication, wakeup, tool loading and result return.
• Runner reuse: keep placement and capability separate.
• Onboarding: watch and resume each connection state.
• Qualification: test lost responses, duplicate wakeups, restarts, authority loss and cleanup.
• Deployment: keep one environment manifest and verify the live tenant.

Safety notes on scripts and network access

The skill itself runs no scripts and uses no network of its own. It is a set of instructions, so the actions it describes are carried out by you and your agent under your own supervision.

The workflow does involve real systems. It asks for a stable public HTTPS endpoint, a live provider account, and a deployed tenant. The skill says to keep secrets out of the environment manifest and to retain test environments only while the user and provider are testing. It also says the skill grants no new permission to message, grant access, spend, publish, or deploy. Apply your own authorisation and your host's policies before running any step.

• Runs scripts: no
• Uses network: no (the workflow you follow does contact the provider and your test endpoint)
• Keep credentials, pairing codes and temporary ingress hosts out of shared records.

Tips for getting useful results

Treat a provider saying the task is done as a claim, not proof. The skill expects you to check task disposition and cleanup yourself. Keep simulated, real-provider and real-deployment evidence separate, so you do not overstate what has been proven.

If setup needs a reboot, app reattachment or a manual nudge, record the functional success and the onboarding defect separately. Do not describe a process as self-serve when it needed hand intervention.

• Name the level your 'works' claim reaches: prototype, real provider, real Runner, managed sandbox, deployed tenant or unattended first-time onboarding.
• For restart tests, confirm the controller actually restarted, since a test where it did not is invalid.
• Use the skill's references for dated case-study context, but verify current provider documentation before changing code.