Skip to content
Get packs

Guide · Agent skill

How to use the Create Paperclip Plugin agent skill

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

The paperclip-create-plugin skill is a step-by-step playbook that tells an AI agent how to build an add-on plugin for Paperclip, a local AI agent platform. It is written for developers who extend a local Paperclip instance and want plugins kept apart from Paperclip's core code. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what checks the agent runs before reporting back.

Create Paperclip Pluginpaperclipai/paperclip · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Prepare Paperclip and tools. Make sure a Paperclip checkout, the paperclipai CLI, pnpm and Node.js are available, and that a local Paperclip instance is running.
  3. 3Ask for a plugin in plain language. Describe the plugin you want and where it should live, outside the Paperclip checkout by default.
  4. 4Scaffold with paperclipai plugin init. The agent runs the init command with your name and output directory, then follows the next commands it prints.
  5. 5Install and watch the build. Run pnpm install and pnpm dev in the plugin folder, then paperclipai plugin install with the absolute path. Edits rebuild without reinstalling.
  6. 6Verify and review the report. Run pnpm typecheck, pnpm test and pnpm build, then check the success checklist for scaffold path, commands, install status and results.

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

An agent skill is a folder of instructions, centred on a SKILL.md file, that an AI agent loads when a task matches the skill's description. This skill covers creating and iterating on external Paperclip plugins with a CLI-first workflow.

With the skill active, the agent scaffolds a new plugin folder outside the Paperclip checkout, installs it into a running Paperclip instance from a local path, rebuilds it while you edit, and runs typecheck, test and build checks. It then reports results using a standard checklist.

  • Scaffolds the plugin into a directory outside the Paperclip code, for example ~/dev/paperclip-plugins/<name>.
  • Installs it into the running instance by local absolute path.
  • Relies on a watch build so you do not reinstall after every edit for local-path plugins.
  • Reports scaffold path, commands run, install status, test and build results, and reload limitations.

Install the skill in Claude

You have two options. For a personal setup, download the ZIP from this page and unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder instead.

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

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

Prepare your environment before you start

The skill assumes a Paperclip checkout with the paperclipai CLI on your PATH. If the CLI is missing, the skill falls back to running a local build script with pnpm and Node.js. You also need pnpm, Node.js, and a running local Paperclip instance to install plugins into.

This is a developer workflow. It assumes you are comfortable with a command line, pnpm and TypeScript.

  • Paperclip checkout with paperclipai on PATH (or pnpm and Node for the fallback path)
  • pnpm
  • Node.js
  • A running local Paperclip instance

Trigger the skill with natural requests

You do not need to name commands. Describe the task and mention plugins and Paperclip. The skill's description covers scaffolding a plugin, iterating on a local plugin, installing it into Paperclip, and updating plugin authoring docs.

Be specific about the plugin name and location if you have a preference, since the skill scaffolds outside the Paperclip checkout by default.

  • "Create a new Paperclip plugin called @acme/my-plugin in ~/dev/paperclip-plugins."
  • "Scaffold a Paperclip connector plugin and install it into my local instance."
  • "I changed my Paperclip plugin's worker code. Rebuild it and check the install status."
  • "Run the typecheck, tests and build for my Paperclip plugin and report the results."

Scaffold and install a plugin

The skill uses paperclipai plugin init to create the package. The command creates a folder named after the unscoped package name inside the output directory. On success it prints the exact next commands, which the agent runs in order.

Inside the new folder, the rebuild loop is pnpm install, then pnpm dev (an esbuild watch that rebuilds dist/manifest.js, dist/worker.js and dist/ui/), then paperclipai plugin install with the absolute path. Local-path installs are detected automatically from absolute, ./, ../, ~ or an existing relative folder. Pass --local to force local mode if the detection is ambiguous.

  • --output <dir> sets the parent directory; defaults to the current directory.
  • --template <default|connector|workspace|environment> picks a starter template.
  • --category <connector|workspace|automation|ui|environment> sets the manifest category.
  • --display-name, --description and --author set manifest metadata.
  • --sdk-path <path> snapshots a local SDK from a Paperclip checkout, useful for unreleased SDK work.
  • --version applies only to npm installs and is an error with a local path.
paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins pnpm install pnpm dev paperclipai plugin install /absolute/path/to/my-plugin

Check the plugin and run verification

After installing, the agent inspects the plugin with paperclipai plugin list and paperclipai plugin inspect <plugin-key>. It also checks that the manifest declares only supported capabilities, that package.json points its paperclipPlugin block at the dist outputs, and that routePath is used only on page slots.

Before declaring success, the agent runs the three verification commands from the plugin folder. If you changed Paperclip SDK, host or runtime code too, it also runs the relevant workspace checks.

  • Confirm src/manifest.ts, src/worker.ts, src/ui/index.tsx and tests/plugin.spec.ts exist and make sense.
  • Do not use ctx.assets, which the current runtime does not support.
  • Report install status and note any status other than ready, with lastError.
pnpm typecheck pnpm test pnpm build

Safety notes: scripts and the trusted-code model

This skill runs scripts, so review what the agent executes. The source does not list network use: the skill's metadata says it does not use the network. The commands it runs are the paperclipai CLI, pnpm and node.

The skill also documents the runtime model. Plugin workers are trusted code, plugin UI is trusted same-origin host code, and worker APIs are capability-gated. Plugin UI is not sandboxed by manifest capabilities. Treat any plugin you build as code with real access to your instance.

  • The skill runs scripts; check commands before approving them in an agent session.
  • Do not edit Paperclip core unless you explicitly ask for a bundled example, since core changes touch shared server files.
  • Plugin workers and UI are trusted code, not sandboxed.

What people use it for

  • Scaffolding a connector plugin that links Paperclip to an outside service in a folder separate from Paperclip's code.
  • Iterating on a local plugin's worker code while pnpm dev rebuilds the output and the server restarts the worker.
  • Checking a plugin's install status and last error with paperclipai plugin list and inspect after a failed install.
  • Preparing a plugin for later npm publishing while still developing it through local-path installs.

Frequently asked questions

Is the Create Paperclip Plugin skill free to use?

The source says the skill is released under the MIT licence. It does not list prices, so check the licence file in the repository for the exact terms.

What do I need before using this skill?

You need a Paperclip checkout with the paperclipai CLI on your PATH, or pnpm and Node.js for the fallback path. You also need pnpm, Node.js, and a running local Paperclip instance to install plugins into.

How do I install the paperclip-create-plugin skill?

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

Does this skill work for non-developers?

Not really. It assumes knowledge of the command line, pnpm and TypeScript. If you only want to use Paperclip, this skill is not the right tool.

Why does the skill build plugins outside Paperclip's core code?

The skill treats plugins as their own packages. It keeps plugin source out of packages/plugins/ unless you explicitly ask for a bundled example, because core changes touch shared server files. Local-path installs are the supported development model.

Do I need to reinstall the plugin after every change?

No, for local-path plugins. The server watches the built dist outputs and restarts the plugin worker on rebuild, and pnpm dev keeps rebuilding. The skill does note that some changes, such as manifest changes, may need a reinstall, so the agent reports any limitations.

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 this skill if you are a developer extending a local Paperclip instance and want plugins kept separate from core code, with the agent handling scaffolding, install and checks. Pick something else if you only want to use Paperclip, or if you need plugin changes bundled into Paperclip core, which this skill tries to avoid.

Download the skill