Create a Paperclip Plugin
Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
1. Ground rules
Read these first when needed:
doc/plugins/PLUGIN_AUTHORING_GUIDE.mdpackages/plugins/sdk/README.mddoc/plugins/PLUGIN_SPEC.mdonly for future-looking context
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.assetsis not supported in the current runtime
2. Preferred workflow
Use the scaffold package instead of hand-writing the boilerplate:
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>For a plugin that lives outside the Paperclip repo, pass --sdk-path and let the scaffold snapshot the local SDK/shared packages into .paperclip-sdk/:
pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
--output /absolute/path/to/plugin-repos \
--sdk-path /absolute/path/to/paperclip/packages/plugins/sdkRecommended target inside this repo:
packages/plugins/examples/for example plugins- another
packages/plugins/<name>/folder if it is becoming a real package
3. After scaffolding
Check and adjust:
src/manifest.tssrc/worker.tssrc/ui/index.tsxtests/plugin.spec.tspackage.json
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
routePathonly onpageslots - is installed into Paperclip from an absolute local path during development
4. If the plugin should appear in the app
For bundled example/discoverable behavior, update the relevant host wiring:
- bundled example list in
server/src/routes/plugins.ts - any docs that list in-repo examples
Only do this if the user wants the plugin surfaced as a bundled example.
5. Verification
Always run:
pnpm --filter <plugin-package> typecheck
pnpm --filter <plugin-package> test
pnpm --filter <plugin-package> buildIf you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
6. Documentation expectations
When authoring or updating plugin docs:
- distinguish current implementation from future spec ideas
- be explicit about the trusted-code model
- do not promise host UI components or asset APIs
- prefer npm-package deployment guidance over repo-local workflows for production