Agent skill · software engineering · paperclipai
paperclip-dev-workspace-run-verify-fix
Run, verify, reseed, and repair Paperclip isolated dev workspace services. Use when asked to start or fix a managed project/worktree service and prove health, login readiness, cloned data, runtime visibility, and correct port ownership.
Why this skill is useful
Adds executable scripts and detailed procedures for managing and verifying Paperclip development workspaces that aren't covered in public documentation.
What it needs
Requires paperclip installed locally. About 12k tokens when loaded. Last updated 2026-08-07. 75,771 stars on the source repository.
What this skill does
Paperclip Dev Workspace Run / Verify / Fix This skill is for Paperclip-specific development workspaces whose service is started through project execution workspace runtime services, typically a worktree service such as paperclip-dev. Success means all of these are true: the service was started through the normal managed runtime path, not a detached workaround the worktree database is a full bootstrapped isolated clone of the primary instance database /api/health returns status: ok and bootstrapStatus: ready the root page returns 200 and does not show the first-admin setup gate the board user can log in with their normal dev credentials the app shows populated cloned data, not only a manually copied auth user the main control plane shows the service as running / healthy with the expected URL the served workspace app also knows about that service and shows it as running / healthy the process that owns the service port really belongs to the target workspace: readlink /proc/<pid>/cwd resolves inside the target worktree, not a sibling workspace If any item fails, keep fixing. Do not mark the issue done because one probe passed. Hard rules The master checkout /srv/paperclip/home/paperclipai/paperclip (the primary repo with the real instance .env) is never a workspace repair target. Never point a worktree runtime service at it, never git worktree add into it or under <master>/.paperclip/worktrees/, and never edit its .env while repairing a workspace. Managed workspaces run in their own folders, for example ~/.paperclip-worktrees/instances/<slug>/…. Never trust a running / healthy runtime row or a passing /api/health alone. The service:paperclip-dev port is pinned in service config, so a sibling workspace's process can own the port and still answer health checks. Confirm the port owner's real cwd (readlink /proc/<pid>/cwd) before and after every repair; the runtime row's recorded cwd and pid can be fabricated by port adoption. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills paperclipai/paperclip-dev-workspace-run-verify-fix