How to use the Fix Failed Paperclip Runs agent skill

What is an agent skill and what does this one do?

An agent skill is a folder of instructions that an AI agent loads when a request matches the skill's description. This skill is a repair playbook for maintaining the Paperclip project itself. It is not a general tool for people who only want to run Paperclip tasks.

Once triggered with a task or run URL, or a failure report, the skill directs the agent through a fixed sequence: establish the incident and the finish line, find the first causal failure, prove the bug with a regression test that fails before any fix, repair the cause, check side effects, verify the real workflow and deliver a pull request whose checks pass.

• Traces the root cause from logs, run records and task activity
• Writes a test that reproduces the bug and fails before the fix
• Makes a targeted repair and checks second-order effects
• Delivers a pull request whose checks pass
• Consults a failure-patterns reference for matching mechanisms to test

Install the fix-failed-paperclip-run skill

Download the ZIP for this skill from this page and unzip it into one of two locations. Use ~/.claude/skills/ to make the skill available to all your projects, or a project's .claude/skills/ folder to make it available only to that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the skill with a natural request?

You do not need a special command. Describe the failure and include the task or run URL, or paste the failure report. Requests that name a failed, stuck, slow or incorrectly blocked task or run match the skill's description.

The skill asks the agent to resolve missing facts from available tools and records before asking you. You can still add context such as the affected instance, the time window or the result you expect.

• Include the task or run URL whenever you have it
• Say what went wrong: failed, stuck, slow or wrongly blocked
• State whether you want only a verified fix and green PR, or also rollout and recovery

Example requests that work well

Good requests are specific about the symptom and the evidence. The examples below show the kind of input the skill is written for.

• Run https://example.invalid/task/123 failed after a server restart. Find the root cause, add a regression test that fails first, and open a PR with passing checks.
• This run has been stuck in waiting for several hours. Trace why no next action was taken and propose a tested fix.
• Our agent marked this task blocked, but the approval was already granted. Investigate the wrong block and deliver a PR.

What the skill needs before it can work

The skill assumes you are working on the Paperclip codebase with access to its tooling. It reads doc/execution-semantics.md for the execution contract and references/failure-patterns.md for failure mechanisms. Reads of instance data are company-scoped, and the skill says it must not bypass a scoping boundary.

• Access to the Paperclip repository
• Access to instance logs, run records and task URLs with company-scoped read access
• Repository tooling to run tests and open pull requests, such as git and a GitHub account
• The files doc/execution-semantics.md and references/failure-patterns.md inside the repository

Safety notes: scripts, network and merging

This skill runs scripts and uses the network. It is written for a maintainer's environment, not for production systems. Review what the agent runs before you approve it, and keep credentials out of code, fixtures, skills and PR descriptions. The skill says to redact credential values in its evidence record.

The skill states that it does not itself authorize merging or deploying. A passing unit test or a green PR is not the same as a verified workflow in production. Human review is still needed for any rollout, especially for production incidents where the agent might push or deploy changes.

• The skill runs scripts and uses the network
• Redact credential values and keep secrets out of public code and PR text
• Merging and deployment are not authorized by this skill alone
• Human review is still needed for rollouts

Tips for getting a useful result

The skill expects a regression test that fails before the fix. If the agent cannot observe a meaningful red, it is meant to report that gap rather than claim proof. Check that the test fails on the unfixed code and passes after the change.

Give the agent the time window and the instance context. The skill notes that multiple failed runs can have different causes, so treat each run separately.

• Ask for the red-then-green regression test to be shown in the PR
• Preserve logs before retries or cleanup, as the skill recommends
• Expect the agent to check whether an existing fix already covers the defect before writing new code