Paperclip Create Plugin
Scaffold and iterate on external Paperclip plugins against a local Paperclip instance using the CLI install loop instead of editing core.
Overview
paperclip-create-plugin is an agent skill for the Build phase that scaffolds and develops external Paperclip plugins via the CLI init/install loop against a local instance.
Install
npx skills add https://github.com/paperclipai/paperclip --skill paperclip-create-pluginWhat is this skill?
- CLI-first loop: `paperclipai plugin init` and `paperclipai plugin install <path>` against a running instance
- Default workflow keeps plugin source outside Paperclip core unless bundled examples are explicitly requested
- Documents worker/UI rebuild and reload semantics so local edits show up in the running app
- Points to PLUGIN_AUTHORING_GUIDE, SDK README, and PLUGIN_SPEC for authoritative details
- Includes a required success checklist after scaffold and install
Adoption & trust: 1.5k installs on skills.sh; 69.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need a Paperclip plugin but lack a repeatable way to scaffold it outside core, install it locally, and verify reload semantics without breaking the main repo.
Who is it for?
Builders already running Paperclip locally who want to add or refine a plugin package with the documented CLI workflow.
Skip if: Teams that only want a one-line config tweak in core, or users not running a local Paperclip instance for path-based plugin install.
When should I use this skill?
Scaffolding a new Paperclip plugin, working on a local plugin against a running Paperclip instance, or updating plugin authoring docs.
What do I get? / Deliverables
You get an external plugin package wired into your running Paperclip instance with rebuild/reload understood and a success checklist completed before you ship the plugin further.
- External plugin package scaffolded via CLI
- Plugin installed by path into local Paperclip
- Completed plugin success checklist
Recommended Skills
Journey fit
Plugin authoring is product extension work that happens while you are building agent infrastructure around Paperclip. Paperclip plugins extend the agent runtime and UI; the skill targets plugin packages and worker reload semantics, not generic app frontend.
How it compares
Use this workflow skill instead of hand-copying example folders into `packages/plugins/` without the install loop.
Common Questions / FAQ
Who is paperclip-create-plugin for?
Solo and indie builders extending Paperclip with custom plugins using paperclipai CLI against a local instance, plus agents helping them scaffold and iterate safely outside core.
When should I use paperclip-create-plugin?
Use when scaffolding a new plugin, developing a local plugin against a running Paperclip app, or updating plugin authoring docs; during Build when you are adding agent-tooling integrations on Paperclip.
Is paperclip-create-plugin safe to install?
The skill guides local CLI and filesystem work on your machine; review the Security Audits panel on this Prism page before trusting third-party skill sources and avoid installing untrusted plugins into production instances without review.
SKILL.md
READMESKILL.md - 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. ```bash 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: ```bash 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: ```bash 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