How to use the Paperclip Dev Workspace Repair agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file. The file holds instructions that an AI agent reads when a task matches the skill's description, so the agent follows a defined procedure instead of improvising.

This skill is named paperclip-dev-workspace-run-verify-fix and is released under the MIT licence. Its SKILL.md is the only file listed for it.

What the skill makes the agent do

The skill is for a Paperclip development workspace whose service is started through a project execution workspace runtime service, typically a worktree service such as paperclip-dev. The agent does not declare success until every check passes. Those checks include:

• 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, and the app shows populated cloned data.
• The main control plane and the served workspace app both show the service as running and healthy.
• The process owning the service port really belongs to the target worktree, confirmed with readlink /proc/<pid>/cwd.

Install the skill

Download the skill ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: <your project>/.claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

The skill's description says it applies when asked to start or fix a managed project or worktree service and prove health, login readiness, cloned data, runtime visibility and correct port ownership. You do not need to name the skill. Ask for the outcome you want, and mention the workspace or service.

The skill expects the agent to work from the current Paperclip issue. It collects inputs such as PAPERCLIP_API_URL, PAPERCLIP_API_KEY and the expected service URL from environment variables where available. It will not print API keys or passwords.

• Start the paperclip-dev workspace service for this issue and verify it.
• The paperclip-dev service is healthy but the page shows the wrong workspace. Fix it.
• Restart the stale workspace service and prove the login works with cloned data.
• Check who owns port 40631 and repair the workspace if a sibling process holds it.

Understand the port-ownership check

The service pins an explicit port in its config, so every workspace that runs it claims the same port. A sibling workspace's process can hold that port and still answer health checks, so a green status can be misleading.

The skill's identity check finds the process listening on the port and reads its working directory. The resolved path must be inside the target worktree, usually <worktree>/server.

Examples of what the agent does

In a typical repair, the agent reads the latest issue comment, inspects runtime state from the main control plane, checks the port owner, stops any conflicting owner through its managed control path, reseeds the worktree from the primary instance if database completeness is in doubt, starts the service through the managed runtime API, and then verifies everything from both the control plane and the served app.

If a check fails, the agent loops back to the narrowest repair step rather than marking the issue done.

What the skill needs

The skill is written for a Paperclip checkout and its environment. It requires access to a Paperclip control plane API (PAPERCLIP_API_URL) and an agent API key. The checkout must include doc/DEVELOPING.md, which the agent is told to read before running CLI, dev server, worktree, database, build or test commands.

Shell tools such as curl and readlink are used, and readlink needs /proc access, so it is Linux-oriented. Node, pnpm and an embedded Postgres setup are used indirectly through the Paperclip CLI.

• Access to a Paperclip control plane API and agent API key
• A Paperclip checkout with doc/DEVELOPING.md and a worktree environment
• curl and readlink on Linux (/proc access)
• Node/pnpm and embedded Postgres, used through the Paperclip CLI

Safety notes: scripts and network

This skill runs scripts and uses the network. It calls the Paperclip runtime-service start and stop endpoints, and it can stop processes and replace a workspace database clone. The skill's hard rules say the master checkout is never a repair target, that the agent must not edit its .env during a repair, and that it must avoid destructive git or database actions and preserve user changes in the worktree.

Review the actions before approving destructive reseeds. The skill is not meant for running reseeds without review.

• Never point a worktree runtime service at the master checkout.
• Do not use psql or ad hoc row copying for the normal fix path.
• Copying only auth rows is not accepted as a final fix.

Tips for good results

Give the issue ID and the expected service URL so the agent does not have to guess. If the service command ID or execution workspace ID is missing, the skill tells the agent to read the issue, project or execution-workspace records rather than start an unmanaged server on a random port.

Expect the agent to run the smallest verification that proves the repair. It adds focused tests only when code changed.

• Provide the execution workspace ID and expected service URL.
• Ask for a final comment on the issue with root cause, fix and verification.
• Do not paste passwords into the request; the skill never posts them.