Update create-agent-skills to match 2026 official docs, add /triage-prs command
- Rewrite SKILL.md to document that commands and skills are now merged - Add new frontmatter fields: disable-model-invocation, user-invocable, context, agent - Add invocation control table and dynamic context injection docs - Fix skill-structure.md: was incorrectly recommending XML tags over markdown headings - Update official-spec.md with complete 2026 specification - Add local /triage-prs command for PR triage workflow - Add PR triage plan document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
193
.claude/commands/triage-prs.md
Normal file
193
.claude/commands/triage-prs.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
name: triage-prs
|
||||
description: Triage all open PRs with parallel agents, label, group, and review one-by-one
|
||||
argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git log *)
|
||||
---
|
||||
|
||||
# Triage Open Pull Requests
|
||||
|
||||
Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
|
||||
|
||||
## Step 0: Detect Repository
|
||||
|
||||
Detect repo context:
|
||||
- Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
|
||||
- Current branch: !`git branch --show-current 2>/dev/null`
|
||||
|
||||
If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
|
||||
|
||||
## Step 1: Gather Context (Parallel)
|
||||
|
||||
Run these in parallel:
|
||||
|
||||
1. **List all open PRs:**
|
||||
```bash
|
||||
gh pr list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
2. **List all open issues:**
|
||||
```bash
|
||||
gh issue list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
3. **List existing labels:**
|
||||
```bash
|
||||
gh label list --repo OWNER/REPO --limit 50
|
||||
```
|
||||
|
||||
4. **Check recent merges** (to detect duplicate/superseded PRs):
|
||||
```bash
|
||||
git log --oneline -20 main
|
||||
```
|
||||
|
||||
## Step 2: Batch PRs by Theme
|
||||
|
||||
Group PRs into review batches of 4-6 based on apparent type:
|
||||
|
||||
- **Bug fixes** - titles with `fix`, `bug`, error descriptions
|
||||
- **Features** - titles with `feat`, `add`, new functionality
|
||||
- **Documentation** - titles with `docs`, `readme`, terminology
|
||||
- **Configuration/Setup** - titles with `config`, `setup`, `install`
|
||||
- **Stale/Old** - PRs older than 30 days
|
||||
|
||||
## Step 3: Parallel Review (Team of Agents)
|
||||
|
||||
Spawn one review agent per batch using the Task tool. Each agent should:
|
||||
|
||||
For each PR in their batch:
|
||||
1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
|
||||
2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
|
||||
3. Determine:
|
||||
- **Description:** 1-2 sentence summary of the change
|
||||
- **Label:** Which existing repo label fits best
|
||||
- **Action:** merge / request changes / close / needs discussion
|
||||
- **Related PRs:** Any PRs in this or other batches that touch the same files or feature
|
||||
- **Quality notes:** Code quality, test coverage, staleness concerns
|
||||
|
||||
Instruct each agent to:
|
||||
- Flag PRs that touch the same files (potential merge conflicts)
|
||||
- Flag PRs that duplicate recently merged work
|
||||
- Flag PRs that are part of a group solving the same problem differently
|
||||
- Report findings as a markdown table
|
||||
- Send findings back via message when done
|
||||
|
||||
## Step 4: Cross-Reference Issues
|
||||
|
||||
After all agents report, match issues to PRs:
|
||||
|
||||
- Check if any PR title/body mentions `Fixes #X` or `Closes #X`
|
||||
- Check if any issue title matches a PR's topic
|
||||
- Look for duplicate issues (same bug reported twice)
|
||||
|
||||
Build a mapping table:
|
||||
```
|
||||
| Issue | PR | Relationship |
|
||||
|-------|-----|--------------|
|
||||
| #158 | #159 | PR fixes issue |
|
||||
```
|
||||
|
||||
## Step 5: Identify Themes
|
||||
|
||||
Group all issues into themes (3-6 themes):
|
||||
- Count issues per theme
|
||||
- Note which themes have PRs addressing them and which don't
|
||||
- Flag themes with competing/overlapping PRs
|
||||
|
||||
## Step 6: Compile Triage Report
|
||||
|
||||
Present a single report with:
|
||||
|
||||
1. **Summary stats:** X open PRs, Y open issues, Z themes
|
||||
2. **PR groups** with recommended actions:
|
||||
- Group name and related PRs
|
||||
- Per-PR: #, title, author, description, label, action
|
||||
3. **Issue-to-PR mapping**
|
||||
4. **Themes across issues**
|
||||
5. **Suggested cleanup:** spam issues, duplicates, stale items
|
||||
|
||||
## Step 7: Apply Labels
|
||||
|
||||
After presenting the report, ask user:
|
||||
|
||||
> "Apply these labels to all PRs on GitHub?"
|
||||
|
||||
If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
|
||||
|
||||
## Step 8: One-by-One Review
|
||||
|
||||
Use **AskUserQuestion** to ask:
|
||||
|
||||
> "Ready to walk through PRs one-by-one for merge/comment decisions?"
|
||||
|
||||
Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
|
||||
|
||||
### Show the PR:
|
||||
|
||||
```
|
||||
### PR #<number> - <title>
|
||||
Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
|
||||
Label: <label>
|
||||
|
||||
<1-2 sentence description>
|
||||
|
||||
Fixes: <linked issues if any>
|
||||
Related: <related PRs if any>
|
||||
```
|
||||
|
||||
Show the diff (trimmed to key changes if large).
|
||||
|
||||
### Ask for decision:
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
- **Merge** - Merge this PR now
|
||||
- **Comment & skip** - Leave a comment explaining why not merging, keep open
|
||||
- **Close** - Close with a comment
|
||||
- **Skip** - Move to next without action
|
||||
|
||||
### Execute decision:
|
||||
|
||||
- **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
|
||||
- If PR fixes an issue, close the issue too
|
||||
- **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
|
||||
- Ask user what to say, or generate a grateful + specific comment
|
||||
- **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
|
||||
- **Skip:** Move on
|
||||
|
||||
## Step 9: Post-Merge Cleanup
|
||||
|
||||
After all PRs are reviewed:
|
||||
|
||||
1. **Close resolved issues** that were fixed by merged PRs
|
||||
2. **Close spam/off-topic issues** (confirm with user first)
|
||||
3. **Summary of actions taken:**
|
||||
```
|
||||
## Triage Complete
|
||||
|
||||
Merged: X PRs
|
||||
Commented: Y PRs
|
||||
Closed: Z PRs
|
||||
Skipped: W PRs
|
||||
|
||||
Issues closed: A
|
||||
Labels applied: B
|
||||
```
|
||||
|
||||
## Step 10: Post-Triage Options
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
|
||||
1. **Run `/release-docs`** - Update documentation site if components changed
|
||||
2. **Run `/changelog`** - Generate changelog for merged PRs
|
||||
3. **Commit any local changes** - If version bumps needed
|
||||
4. **Done** - Wrap up
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **DO NOT merge without user approval** for each PR
|
||||
- **DO NOT force push or destructive actions**
|
||||
- Comments on declined PRs should be grateful and constructive
|
||||
- When PRs conflict with each other, note this and suggest merge order
|
||||
- When multiple PRs solve the same problem differently, flag for user to pick one
|
||||
- Use Haiku model for review agents to save cost (they're doing read-only analysis)
|
||||
Reference in New Issue
Block a user