How to use the Diagnose Why Work Stopped agent skill

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

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a request matches the skill's description. This skill is a compatibility entry point. It does not hold the full repair workflow itself. Instead, it sends the agent to the fuller Fix Failed Paperclip Run skill for the complete diagnosis, regression, repair, verification, and pull request process.

• Finds the first causal failure in work that failed, stalled, looped, or over-recovered.
• Reads the current doc/execution-semantics.md and inspects the relevant subtree and recent repairs.
• Classifies each non-progressing node as a genuine wait, agent-actionable but unrouted, or already covered.
• Honors an explicit request for diagnosis only, so the agent investigates without implementing a fix.

How do you install the skill?

You can add the skill in two ways. Download the ZIP from the skill's page on this site and unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it limited to one repository. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill is only useful alongside the Paperclip repository. Make sure you also have the doc/execution-semantics.md file and the linked fix-failed-paperclip-run skill available, because the instructions point to them.

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

How do you trigger the skill with a natural request?

You do not need a special command. The agent decides to use the skill when your request matches its description, so describe the problem in plain terms. Name the symptom, the issue or subtree involved, and whether you want a diagnosis only.

• Why did the Paperclip task for this issue fail and stop retrying?
• Diagnose why this issue subtree has stalled. Diagnosis only, no code changes.
• This task keeps looping through recovery. Work out whether it is a real wait or unrouted work.
• Check whether this blocked node is already covered by another issue before we duplicate it.

What does a diagnosis look like in practice?

The agent first reads the execution semantics document, then walks the relevant issue tree and its recent repairs. For each node that is not moving, it decides which of three categories applies and names the next action and its owner. The three categories are below.

A genuine wait means a named human or external dependency must act, for example an approval, credentials, or budget. Agent-actionable but unrouted work is authorized useful work that has no live path to be picked up. Already covered work is owned by existing work, so the right move is to avoid duplicating it.

• Genuine wait: a named human or external dependency must act.
• Agent-actionable but unrouted: authorized useful work lacks a live path.
• Already covered: existing work owns the next action; do not duplicate it.

What principles should a good repair follow?

The skill asks the agent to keep three invariants together. Productive work must have a real next action and owner. Only genuine blockers, including approval, credentials, and budget, should stop work. Recovery must be bounded and must not recursively recover itself.

When a repair is proposed, the skill asks for it to be framed as a general behavioral contract and checked against a productive counterexample. A normal fix request then continues through the Fix Failed Paperclip Run workflow to a pull request with passing checks.

• Invariant 1: productive work has a real next action and owner.
• Invariant 2: only genuine blockers stop work.
• Invariant 3: recovery is bounded and cannot recurse on itself.

What about safety, scripts and network access?

This skill runs no scripts and uses no network access. It is made of instructions in a single SKILL.md file. The work it directs the agent to do happens in the Paperclip codebase and its issue data, so the agent needs access to those.

Be careful with fix requests. A normal request to fix stopped work moves through a workflow that ends in a pull request and does not add a separate approval gate. If you want review before any code changes, say explicitly that you want a diagnosis only, or require approval before implementation.

• Runs scripts: no.
• Uses network: no.
• Historical task links and private incident access are not required.
• An unattended agent should not change code without review, because the fix path does not stop for approval.