Paperclip Create Plugin

Create and develop a Paperclip plugin

Use this skill when the task is to create, scaffold, or iterate on a Paperclip plugin against a local Paperclip instance.

1. Default: build the plugin OUTSIDE Paperclip core

Plugins are their own packages. Unless the task explicitly asks for a bundled in-repo example, do not add plugin source under packages/plugins/ in this repo.

• Scaffold the plugin into a directory outside the Paperclip checkout (e.g. ~/dev/paperclip-plugins/<name>).
• Install it into the running Paperclip instance by local absolute path.
• Edit code in the external package; let Paperclip pick up rebuilt output.

Only edit Paperclip core itself when the user asks to surface a plugin as a bundled example (server/src/routes/plugins.ts, in-repo example lists, docs).

2. Ground rules

Reference docs when you need detail:

1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
2. packages/plugins/sdk/README.md
3. doc/plugins/PLUGIN_SPEC.md — future-looking context only

Current runtime assumptions:

• plugin workers are trusted code
• plugin UI is trusted same-origin host code
• worker APIs are capability-gated
• plugin UI is not sandboxed by manifest capabilities
• no host-provided shared plugin UI component kit yet
• ctx.assets is not supported in the current runtime

3. CLI-first scaffold workflow

Use paperclipai plugin init. Do not invoke the scaffold package node entrypoint by hand unless the CLI command is unavailable in the environment.

paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins

Useful flags (all optional):

• --output <dir> — parent directory; the command creates <dir>/<unscoped-name>/. Defaults to the current directory.
• --template <default|connector|workspace|environment> — starter template.
• --category <connector|workspace|automation|ui|environment> — manifest category.
• --display-name <name>, --description <text>, --author <name> — manifest metadata.
• --sdk-path <path> — snapshot the local SDK from a Paperclip checkout into .paperclip-sdk/ (useful when developing against an unreleased SDK).

On success the command prints the exact next commands (cd, pnpm install, pnpm dev, paperclipai plugin install <abs-path>). Run them in order.

If paperclipai is not on PATH in your environment, fall back to:

pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
  --output /absolute/path \
  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk

4. Local install + rebuild loop

In the scaffolded plugin folder:

pnpm install
pnpm dev            # esbuild --watch: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
paperclipai plugin install /absolute/path/to/my-plugin

Notes:

• paperclipai plugin install auto-detects local paths (absolute, ./, ../, ~, or an existing relative folder) and forwards isLocalPath: true to the server. Pass --local to force local mode if the heuristic is ambiguous.
• Paths are resolved to absolute paths before being sent to the server.
• The server watches built outputs (dist/) for local-path plugins and restarts the plugin worker on rebuild — you do not need to reinstall after every edit.
• UI hot reload via the SDK dev server (pnpm dev:ui, port 4177) is optional and template-dependent; only mention it if the template wires devUiUrl and you verified it works end to end.
• --version only applies to npm package installs. Combining it with a local path is an error.

After install, inspect with:

paperclipai plugin list
paperclipai plugin inspect <plugin-key>

5. After scaffolding, sanity-check the package

Open and confirm:

• src/manifest.ts — declared capabilities and slots
• src/worker.ts — worker entry
• src/ui/index.tsx — UI entry (if applicable)
• tests/plugin.spec.ts — placeholder test
• package.json — paperclipPlugin block points at dist/manifest.js, dist/worker.js, dist/ui/

Make sure the plugin:

• declares only supported capabilities
• does not use ctx.assets
• does not import host UI component stubs
• keeps UI self-contained
• uses routePath only on page slots