Guide · Agent skill

How to use the Verify Paperclip agent skill: install and run

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

Verify Paperclip is an agent skill from the paperclipai/paperclip repository that gives an AI agent a structured procedure for checking whether the Paperclip project works. It is for contributors who need to verify a change before merging, release testers checking a published npm package, and QA staff validating a staging deployment. After this guide you will know what the skill does, how to install it, how to ask an agent to use it, and what it needs before it runs.

Verify Paperclippaperclipai/paperclip · MIT Download the skill

Quick start

1Download and unzip the skill. Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ or in a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
2Prepare the repository. Check out the Paperclip repository, then run pnpm install --frozen-lockfile from its root. Confirm Node.js 24.11 or newer and Python 3 are installed.
3Name the target. Tell the agent what to verify: a checkout, a published npm channel, or a staging or production stack, and the journey you care about.
4Launch an empty instance. For onboarding checks, let the agent run launch.py with fresh data and evidence directories. Keep it running in a foreground terminal.
5Run the doctor check. Run doctor.py against the evidence directory after startup and after any unexpected behavior.
6Collect evidence and stop. Review the saved evidence, then use the stop script to end the instance safely.

What an agent skill is and what this one does

An agent skill is a folder of instructions and optional helper scripts that an AI agent can load when a task matches it. The skill's SKILL.md file describes the procedure, and its references and scripts support specific steps.

When installed, verify-paperclip helps the agent choose what to test: a source checkout, a published npm package, or an existing staging or production server. It then sets up clean or reused data, drives the browser or command line through real user steps, and saves evidence.

Selects the artifact, environment, starting data, platform and journey before testing begins
Starts an isolated local Paperclip instance for first-run onboarding checks and stops it safely
Checks published npm canary or stable packages through the public registry
Routes deployment work to the private Cloud skills rather than performing it itself

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. To make it available to every project on your machine, place the skill folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside the project root
Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements before you start

The skill's launch scripts expect the Paperclip repository layout and installed dependencies. Without the repository checked out, the skill will not work as intended.

Node.js 24.11 or newer
Python 3 and lsof
pnpm, with dependencies installed using pnpm install --frozen-lockfile
Playwright Chromium, or an installed Chrome selected with PAPERCLIP_PLAYWRIGHT_CHANNEL
For hosted QA testing only: a dedicated QA account, AgentMail inbox access, and a 1Password service account for credentials

pnpm install --frozen-lockfile

Trigger the skill with a natural request

You do not need special syntax. Describe what you want verified and where. The agent should state the target before it starts, and you can ask it to name the target explicitly if you want to be sure.

If you want a first-run check on an empty local instance, ask for that directly. Requests for cross-platform or release qualification should be stated explicitly, because the skill only expands into them when requested or needed to reproduce a problem.

"Verify the onboarding flow on a fresh checkout of this branch."
"Check that the current npm canary installs and onboards correctly."
"Verify the staging deployment against the QA test account."

Launch an empty local instance and run the checks

For first-run onboarding, the skill creates separate data and evidence directories and starts an empty instance from the repository root. The launcher runs without model credentials, so it covers onboarding and early UI steps only. Keep this command running in a foreground terminal.

After startup, run the read-only doctor script to compare the recorded launcher state. Run it again after any surprising behavior. The skill's stop script ends the instance when you are finished.

The launcher writes launch.json into the evidence directory
Source startup builds shared and plugin packages and migrates the empty database, so the first run can take longer
The doctor script only reads state; the stop script requires the real launch.json from launch.py

VERIFY_DATA_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-verify-XXXXXX")
VERIFY_EVIDENCE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-proof-XXXXXX")
python3 .agents/skills/verify-paperclip/scripts/launch.py \
  --data-dir "$VERIFY_DATA_DIR" --evidence-dir "$VERIFY_EVIDENCE_DIR"

Verify a published npm package

To check the npm experience, the skill resolves the requested channel against the public registry before claiming coverage. A source build or local tarball does not answer whether a user can install and run the package.

canary: prerelease verification
latest: stable npm verification
An explicit version, when requested

npm view paperclipai@canary version --registry=https://registry.npmjs.org
npm view paperclipai@latest version --registry=https://registry.npmjs.org

Safety notes: scripts, network and authorized targets

This skill runs scripts and uses the network. It is scoped to authorized targets, and it can drive real user journeys on a live system. Do not point it at production without explicit authorization.

A verification request alone does not authorize deployment, npm publication, fleet-default changes or a production rollout. Preserve explicit deployment instructions already given, and treat the launcher as a credential-free route. Never record credentials or connection strings in evidence.

Use production only with explicit authorization for that scope
Do not use a fake credential to claim provider or agent-run verification
Hosted testing uses a dedicated QA identity and normal email-code login

What people use it for

A contributor verifying a feature or fix on a source checkout before merging
A release tester confirming that a published npm canary installs and completes onboarding
A QA staff member validating a staging deployment against a defined test account
An engineer reproducing a first-run onboarding problem on an empty local instance

Frequently asked questions

How do I install the verify-paperclip skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to run verify-paperclip?

You need the Paperclip repository checked out, Node.js 24.11 or newer, Python 3, lsof, and dependencies installed with pnpm install --frozen-lockfile. You also need Playwright Chromium or an installed Chrome. Hosted QA testing additionally needs a dedicated QA account, AgentMail inbox access and a 1Password service account.

Is verify-paperclip free and what is its licence?

The source lists the licence as MIT. The source does not state pricing, so check the listing on this page for any cost details.

Does the skill run scripts and use the network?

Yes. The skill runs scripts and uses the network. It is scoped to authorized targets, so use it against production only with explicit authorization.

Can it check an agent run with a live model?

Not through the empty-instance launcher. That launcher deliberately runs without model credentials, so it does not prove an agent run. For live model work, the source points to the documented test-drive command with an authorized, environment-backed credential.

What should I do if the doctor script reports a problem?

Run doctor.py again against the same evidence directory after any surprising behavior and review the recorded launch.json. The doctor script is read-only and only compares the recorded launcher state, so re-running it is safe.

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

Use verify-paperclip if you contribute to the Paperclip repository, test npm releases, or validate staging with a defined QA account, and you are comfortable letting an agent run scripts against authorized targets. Pick something else if you do not have the repository checked out, or if you need a general-purpose tool for production systems without explicit authorization.

Download the skill