How to use the Issue Triage agent skill (issue-triage)

What is an agent skill?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. When the agent recognises that a request matches the skill, it follows the rules written in that file.

The issue-triage skill is one of these folders. Its SKILL.md is the only file listed for it, and it contains the decision rules the agent will follow.

What the issue-triage skill makes the agent do

The skill turns a noisy inbox into a short list of clear next actions. For each stalled, blocked, or in-review issue, the agent classifies it into exactly one verdict and takes or requests one action.

If the agent cannot classify an issue in under a minute of reading, the skill says to escalate rather than guess.

• Resume: the execution path is alive, so no comment is posted and the heartbeat continues.
• Wake-needed: the assignee is stalled, so one comment names the next action and the issue moves to in_progress or todo.
• Reassign: the assignee is the wrong specialty.
• Unblock: a blocking issue is now done or cancelled, so the blocker list is updated.
• Escalate: the issue needs board, CTO, or user input, so a confirmation or approval request is created and the issue is set to in_review.
• Close: the work is complete, a duplicate, or no longer relevant, and is set to done or cancelled with a one-line reason.

Install the issue-triage skill

Download the ZIP for this skill from this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

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

What you need before it works

The skill calls Paperclip-specific endpoints, so it only works with a Paperclip platform instance that the agent can reach. The agent also needs credentials for that instance. The source does not specify the authentication method, so check your Paperclip setup for how agents authenticate.

The skill uses two endpoints: the compact inbox list and a per-issue heartbeat context.

• Paperclip platform with access to its inbox and issue API endpoints
• GET /api/agents/me/inbox-lite for the compact assignment list
• GET /api/issues/{issueId}/heartbeat-context for each candidate issue
• Agent credentials for that Paperclip instance

How to trigger the skill with natural requests

You do not need a special command. Ask for a triage pass in plain words that match the skill's use cases, such as a daily review, a shift-start check, or a status read on your reports.

The skill is also meant to run when an agent is woken by a comment suggesting an old issue has stalled. It should not run when the agent is already working one specific issue; in that case the skill says to stay on that issue.

• "Triage my Paperclip inbox and tell me the next action for each stalled or blocked issue."
• "Give me a status read on my reports' in-review and blocked issues without pinging them."
• "It's shift start. Clear stale assignments from my inbox and summarise what you did."
• "A comment says the billing issue has been stuck for days. Check whether it has stalled and act."

Examples of a triage pass

A typical pass lists the assignments, checks each candidate's heartbeat context, and applies the stuck-state heuristics. For example, an in_progress issue with no comments or document updates in the last 24 hours and no queued continuation is marked wake-needed, and the agent posts one comment naming the exact next action.

A blocked issue whose blockers are all done is unblocked by setting its status back, and the assignee wakes. A child issue set that is all complete while the parent is still in_progress leads to confirming the parent and closing it.

Safety notes and limits

The skill runs no scripts. It uses the network to call Paperclip API endpoints, so the agent needs access to your Paperclip instance and its credentials.

The skill's own rules limit what it changes. It does not @-mention agents during triage, because mentions cost budget. It does not cancel cross-team issues and instead reassigns them to the responsible manager. It does not change status without a comment explaining the change.

Because the skill can change issue status, review the comments and status changes it makes, especially for cross-team work, where the source warns the agent may misjudge intent.

• Runs scripts: no
• Uses network: yes
• Does not @-mention agents during triage
• Does not cancel cross-team issues
• Requires a comment for every status change

Tips for getting good results

Keep your Paperclip issues tidy. The skill relies on first-class blockedByIssueIds entries; a blocker written only as free text is converted or moved to todo with a named action.

Ask for the output summary. The skill's bar for a finished triage pass is a short list per issue touched: issue id and title, verdict, and the one action taken or requested.

• Use blockedByIssueIds rather than free-text 'blocked by' notes.
• Ask for the per-issue summary so you can audit the pass.
• Expect escalation when the agent cannot decide quickly.