Triage Skill: Managing the Issue and External PR Triage Workflow with a State Machine

Skill Overview

Triage is a Claude skill for open-source project maintainers. It places issues and external PRs into a small state machine composed of “classification roles + status roles,” evaluating, validating, and asking follow-up questions for each item, and, when necessary, refining it into a brief that an agent can execute directly.

Applicable Scenarios

1. The issue list is piling up and priorities need to be assessed quickly. When a maintainer describes the request in one sentence (for example, “Show me what needs my attention”), the skill queries the issue tracker and divides items into three groups: “never triaged,” “under evaluation,” and “waiting for the reporter’s response but with new activity.” Each group identifies whether an item is a [PR] or [issue], gives the count, and provides a one-line summary, ordered from oldest to newest. The maintainer can then choose specific items for deeper investigation.

2. Determining whether an issue can be handed off to a background agent for unattended completion. The skill reads the complete issue (body, comments, labels, author, and timestamps; for PRs, it also reads the diff), searches the codebase to confirm whether the request has already been implemented, and checks whether it duplicates a request previously rejected in .out-of-scope/. It then recommends a classification and status, with reasons. Once feasibility is confirmed, it turns the issue into an agent brief and marks it ready-for-agent.

3. External PR triage. If the repository treats external PRs as request entry points, PRs are handled as “issues with code attached” and follow the same roles and state machine. The skill actually checks out the code, runs relevant tests or commands, verifies that the diff truly does what it claims, and then determines the next step.

Core Features

1. A two-classification, five-status labeling system. The classification roles are bug (something is broken) and enhancement (a new feature or improvement). The status roles are needs-triage (awaiting maintainer evaluation), needs-info (waiting for the reporter to provide additional information), ready-for-agent (fully specified and ready to be handed to an AFK agent), ready-for-human (requires human implementation), and wontfix (will not be addressed). Every triaged issue should have exactly one classification role and one status role. If status roles conflict, the skill flags the conflict and asks the maintainer rather than handling it autonomously.

2. Verify first, refine second, assign a status last. The skill does not apply labels without verification: bugs are reproduced according to the reporter’s steps, while PRs are checked out and tested. It then honestly reports one of three outcomes: “confirmed (with code paths),” “unable to reproduce,” or “insufficient information.” Insufficient information is itself a strong signal for needs-info. When a request is still vague, the skill invokes the grilling and domain-modeling skills, asking questions iteratively to clarify the requirements and synchronizing the finalized domain terminology into CONTEXT.md and the ADR.

3. Traceable conclusions. Items marked ready-for-agent include an agent brief. Items marked ready-for-human use the same structure but specify why the work cannot be delegated—such as requiring judgment, external permissions, design decisions, or manual testing. Items marked needs-info receive a Triage Notes document that separately lists confirmed conclusions and the specific questions still requiring answers from the reporter, preventing completed work from being lost. All comments posted to the issue tracker include a statement that “This content was generated by AI during the triage process.”

Frequently Asked Questions

What does the Triage skill do?

It advances issues and external PRs through a fixed state machine: first classifying them as either a bug or an enhancement, then assigning a status role, and ultimately producing an actionable conclusion—either an agent brief, a list of follow-up questions for the reporter, or a closure with an explanation. Its core purpose is to spare maintainers from having to start from scratch when reviewing every item.

Can it process issues automatically, or does it require human confirmation?

Human confirmation is required. This skill is designed to be invoked manually by maintainers only (disable-model-invocation) and will not trigger itself. Before recommending a classification or status, applying labels, posting comments, or closing an issue, it explains what it is about to do. It also asks the maintainer first when a state transition appears unusual. Maintainers can alternatively specify, “Move #42 to ready-for-agent,” in which case the skill skips the refinement stage and executes the instruction directly.

What do the statuses needs-triage, needs-info, and ready-for-agent mean?

needs-triage means the maintainer needs to evaluate the item; needs-info means it is blocked while waiting for additional information from the reporter; ready-for-agent means the request is fully specified and can be handed to an unattended agent; ready-for-human means a human must implement or merge it; and wontfix means it will not be addressed. The normal progression is unlabeled → needs-triage → one of the other four statuses. After the reporter responds, needs-info returns to needs-triage.

Can an issue have two status labels at the same time?

No. It should have exactly one status role. If a conflict is found, the skill flags it and asks the maintainer rather than choosing one autonomously.

Are external PRs triaged too? What about PRs from internal members?

External PRs are included in triage when the repository treats them as request entry points, using the same roles and statuses as issues. The discovery view exposes only external PRs—PRs being developed by collaborators do not count as triage work. This filtering applies only during discovery: when a maintainer explicitly names a PR, it is triaged regardless of its author.

Will triage repeat questions that have already been answered?

No. The skill first parses the existing triage notes on the issue and checks whether the reporter has already answered the outstanding questions. It then provides an updated overall picture without repeating questions that have already been resolved.

How does the skill handle a request that has already been implemented?

It classifies it as an implemented wontfix: closes the issue and, in a comment, points to the implementation location in the code. This situation is not recorded in .out-of-scope/—that knowledge base only records rejected requests, not features that have already been built. If a rejected enhancement request is involved, it is recorded in .out-of-scope/ with a link from the comment; a rejected bug is closed directly with an explanation.

What prerequisites are needed to use this skill?

A label mapping is required to map the skill’s canonical role names to the label strings actually used by your issue tracker. If you do not yet have this mapping, run /setup-matt-pocock-skills first. The skill also reads AGENT-BRIEF.md (how to write persistent briefs) and OUT-OF-SCOPE.md (how the .out-of-scope/ knowledge base works) as reference documents.