Guide · Agent skill

How to use the Issue and PR Triage agent skill (triage)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The triage agent skill teaches an AI agent a repeatable process for working through a project's issue tracker: sorting bug reports, feature requests and external pull requests into a few labelled roles, checking claims, and writing clear briefs for other agents or humans to act on. This guide explains what a skill is, how to install this one, how to trigger it with plain requests, and what it needs before you rely on it. By the end you will know how to set it up safely on a project you maintain.

Issue and PR Triagemattpocock/skills · MIT Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it so the triage folder contains SKILL.md and its reference files.
2Place the skill. Put the folder in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one repository. In the Claude apps, upload it under Settings → Capabilities → Skills.
3Set up the label mapping. Make sure your real tracker labels are mapped to the canonical roles. If no mapping exists, run /setup-matt-pocock-skills.
4Start with a read-only request. Run /triage and ask to see what needs your attention, so you can review the buckets without changing anything.
5Triage one item. Ask about a specific issue or PR, review the recommendation and verification result, then confirm the outcome.
6Review every post. Check each comment, role change and closure before it goes live on the tracker.

What is an agent skill and what does triage do?

An agent skill is a folder of instructions that an AI agent loads when a task matches it. The triage skill is defined in a SKILL.md file and is invoked with /triage. It is written for maintainers of software projects who have a steady flow of issues and outside contributions.

The skill moves each issue or external PR through a small state machine. There are two category roles, bug (something is broken) and enhancement (new feature or improvement), and five state roles: needs-triage, needs-info, ready-for-agent, ready-for-human and wontfix. Every triaged issue should carry exactly one category role and one state role.

Shows you unlabeled issues, needs-triage items, and needs-info items with new reporter activity, oldest first.
Searches the codebase for an existing implementation of a request before treating it as new work.
Checks whether a reported bug reproduces, or whether a PR's diff does what it claims.
Drafts needs-info questions, or an agent brief for items marked ready-for-agent.
Asks you to confirm role changes, comments and closures before acting.

Install the triage skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The files include SKILL.md, AGENT-BRIEF.md, OUT-OF-SCOPE.md and agents/openai.yaml. You have two places to put the folder: your personal skills directory, or a project-specific one.

For all your projects, unzip into ~/.claude/skills/. To limit the skill to one repository, unzip into that project's .claude/skills/ folder. If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside the repository
Claude apps: Settings → Capabilities → Skills

Configure the label mapping before first use

The skill uses canonical role names such as needs-triage and ready-for-agent. Your tracker's actual label strings may differ, so the skill expects a mapping from those role names to your real labels. If no mapping has been provided, the skill tells you to run /setup-matt-pocock-skills.

The setup command is referenced by the skill but is not included in these files, so you may need to create or obtain that mapping separately. Without it, the skill cannot reliably apply labels.

/setup-matt-pocock-skills

Trigger the skill with natural requests

Invoke the skill with /triage and describe what you want in plain language. The agent interprets the request and acts on it. The skill is set to disable model invocation, so it runs when you call it rather than deciding on its own to start. Use these request styles:

"Show me anything that needs my attention"
"Let's look at #42" (works for an issue or a PR)
"Move #42 to ready-for-agent"
"What's ready for agents to pick up?"

/triage Show me anything that needs my attention

Work through a single issue or PR

When you ask about a specific item, the skill gathers context, recommends a category and state, and waits for your direction. It then verifies the claim before any deeper discussion. For a bug it tries to reproduce the reporter's steps. For a PR it checks out the branch and runs the relevant tests or commands. It reports the result as confirmed, failed, or insufficient detail.

Depending on the outcome, the skill applies the matching action. Ready-for-agent items get an agent brief comment. Needs-info items get triage notes listing what has been established and what is still needed from the reporter. Wontfix items are closed with a comment that depends on why they were rejected or found to be already implemented.

Already implemented: point to where the change lives in the codebase; do not write to .out-of-scope/.
Rejected bug: give a polite explanation, then close.
Rejected enhancement: record it in .out-of-scope/, link to it in a comment, then close.
Quick override: if you say "move #42 to ready-for-agent", the skill applies the role directly after confirming, and skips grilling.

Understand what the skill writes to your tracker

Every comment or issue the skill posts during triage must begin with the disclaimer that it was generated by AI during triage. The skill asks you to confirm role changes, comments and closures, but a mistaken posting or closure on a live tracker is still a real action, so review each proposal carefully.

The skill also writes persistent files in the repository. Rejected enhancement requests go into a .out-of-scope/ directory, one file per concept, which records why the request was declined. During grilling the skill may update GLOSSARY.md and ADRs as decisions are made.

> *This was generated by AI during triage.*

Safety notes: scripts and network access

The skill runs scripts and uses the network. It needs access to your issue tracker's API, and for PR verification it needs to check out code and run tests on your machine. Only install it on repositories where you are comfortable with an agent running those commands.

The skill is not designed for security-sensitive reports. It has no guidance on private disclosure and would post comments to the tracker, so do not run it on vulnerability reports in a public tracker.

Requires an issue tracker with API access and a configured label mapping.
Requires access to the codebase and the ability to run tests for PR verification.
Requires the Skill tool, because the workflow calls the grilling and domain-modeling skills.
Keep human review on every posted comment and closure.

What people use it for

Sorting a backlog of bug reports into needs-info questions and reproduced bugs ready for an agent.
Checking whether a feature request is already implemented by searching the codebase for the underlying concept.
Verifying an external pull request by checking out its branch and running the tests before deciding on merge.
Preparing a detailed agent brief for a change that a coding agent will build later.
Recording a rejected feature idea in .out-of-scope/ so the same request can be answered consistently later.

Frequently asked questions

Is the triage agent skill free to use?

The source files do not state a licence fee; the skill is listed under the MIT licence. Check the licence file you received for the terms that apply to your use.

What do I need before the triage skill works?

You need an issue tracker with API access, a configured label mapping between the skill's role names and your real labels, access to the codebase, and the Skill tool. The label mapping is set up with /setup-matt-pocock-skills, which is not included in these files.

How do I install the triage skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does the skill close issues automatically?

No. The skill asks the maintainer to confirm role changes, comments and closures before acting. A closure on a live tracker is still a real-world action, so review each proposal.

Can I use this skill for security vulnerability reports?

Not in a public tracker. The skill has no guidance on private disclosure and would post comments to the tracker, so handle security reports through your own private process.

Does the skill work on pull requests as well as issues?

Yes, if the repository treats external pull requests as a request surface. The skill uses the same roles and states, and for a PR it checks the attached diff, for example by running the relevant tests.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you maintain an open-source or internal project with a steady flow of issues and outside pull requests, and you want consistent labels and written responses. Pick something else if your project has no issue tracker or agreed label scheme, or if you need automated, unsupervised handling of security reports.

Download the skill