github-inbox-triage

Category: Ops & Delivery | Uploader: goshippo | Downloads: 0 | Version: v1.0（Latest）

Triage and clean out GitHub notification inbox. Use when the user mentions GitHub notifications, inbox cleanup, notification triage, or wants to mark notifications as done/read. Also use when they reference github.com/notifications or ask about unread review requests, CI failures, mentions, or deploy approvals.

Changelog: Source: GitHub https://github.com/goshippo/shippo-ai-tools

Directory Structure

Current level: .claude/skills/github-inbox-triage/

📁 scripts/
- 📄 classify-ci-notifications.sh 1.2 KB
- 📄 fetch-mention-context.sh 1.8 KB
- 📄 fetch-notifications.sh 2.2 KB
- 📄 filter-by-pr-state.sh 2.0 KB
- 📄 mark-done.sh 1.2 KB
📄 SKILL.md 6.4 KB

SKILL.md

---
name: github-inbox-triage
description: Triage and clean out GitHub notification inbox. Use when the user mentions GitHub notifications, inbox cleanup, notification triage, or wants to mark notifications as done/read. Also use when they reference github.com/notifications or ask about unread review requests, CI failures, mentions, or deploy approvals.
---

# GitHub Inbox Triage

Process GitHub notifications by category, dismiss what's stale or irrelevant, and surface what needs attention.

## Auth

Scripts use `gh api` which relies on the active `gh` auth session. Verify auth works before starting:

```bash
gh auth status
```

If the token is invalid or expired, re-auth with `gh auth login`.

## Scripts

All scripts are in `scripts/` relative to this skill file. Make them executable before first use:

```bash
chmod +x <skill-path>/scripts/*.sh
```

| Script | Purpose | Input | Output |
|--------|---------|-------|--------|
| `fetch-notifications.sh` | Paginated fetch by reason | reason arg | JSONL with id, title, type, repo, subject_url, comment_url |
| `classify-ci-notifications.sh` | Feature vs main/master branch detection | JSONL | JSONL with `branch_type` field |
| `filter-by-pr-state.sh` | Check if PR/Issue is open/closed/merged | JSONL | JSONL with `state` field, filtered |
| `fetch-mention-context.sh` | Fetch comment body for mentions | JSONL | JSONL with `context` field |
| `mark-done.sh` | Bulk mark as Done (PATCH + DELETE) | one ID per line | progress + counts |

### Important: Always use `--all` flag

The GitHub UI inbox shows both read and unread notifications. The fetch script defaults to unread-only. To match what the user sees in the UI, always pass `--all`:

```bash
<skill-path>/scripts/fetch-notifications.sh <reason> --all
```

Without `--all`, read-but-not-done items won't be processed and will remain visible in the inbox.

### GitHub "Participating" is a composite filter

The GitHub UI's "Participating" filter does not map to a single API reason. It combines:
- `author` — PRs/issues you created
- `comment` — threads you commented on
- `state_change` — state changes on subscribed threads
- `approval_requested` — deployment approval requests

The fetch script handles this automatically when you pass `participating` as the reason.

## Triage Workflow

Process notification types in this order. For each type: fetch, assess, present summary, get confirmation, then act.

Present a brief status line before starting each section so the user knows progress.

### 1. Assigned (reason:assign)

Show all assigned notifications. The user decides what to do with each.

```bash
<skill-path>/scripts/fetch-notifications.sh assign --all > /tmp/gh_assign.jsonl
```

Present the full list. Do not auto-dismiss any.

### 2. Participating (composite: author, comment, state_change, approval_requested)

Only Open PRs/issues matter. Merged and Closed ones are safe to dismiss.

```bash
<skill-path>/scripts/fetch-notifications.sh participating --all > /tmp/gh_participating.jsonl
cat /tmp/gh_participating.jsonl | \
  <skill-path>/scripts/filter-by-pr-state.sh --keep open --output-dismissed /tmp/gh_participating_dismissed.jsonl \
  > /tmp/gh_participating_open.jsonl
```

- Present Open items as needing attention
- Report count of merged/closed items
- After confirmation, dismiss merged/closed:

```bash
cat /tmp/gh_participating_dismissed.jsonl | \
  python3 -c "import sys,json; [print(json.loads(l)['id']) for l in sys.stdin]" | \
  <skill-path>/scripts/mark-done.sh
```

Note: `filter-by-pr-state.sh` makes one API call per notification. For large batches (100+), warn the user it will take a few minutes.

### 3. Mentioned (reason:mention)

The user wants to see the mention context before dismissing. Fetch comment bodies.

```bash
<skill-path>/scripts/fetch-notifications.sh mention --all > /tmp/gh_mention.jsonl
cat /tmp/gh_mention.jsonl | \
  <skill-path>/scripts/fetch-mention-context.sh > /tmp/gh_mention_with_context.jsonl
```

Present each mention with:
- Repo and PR/issue title
- The comment body (truncated to 500 chars)
- Ask the user which ones to mark as Done

### 4. Team Mention (reason:team_mention)

Same handling as individual mentions.

```bash
<skill-path>/scripts/fetch-notifications.sh team_mention --all > /tmp/gh_team_mention.jsonl
cat /tmp/gh_team_mention.jsonl | \
  <skill-path>/scripts/fetch-mention-context.sh > /tmp/gh_team_mention_with_context.jsonl
```

Present with context. User decides which to dismiss.

### 5. Review Requested (reason:review_requested)

Same as participating — only Open PRs need attention.

```bash
<skill-path>/scripts/fetch-notifications.sh review_requested --all > /tmp/gh_review.jsonl
cat /tmp/gh_review.jsonl | \
  <skill-path>/scripts/filter-by-pr-state.sh --keep open --output-dismissed /tmp/gh_review_dismissed.jsonl \
  > /tmp/gh_review_open.jsonl
```

- Present Open PRs as needing review
- Dismiss merged/closed after confirmation

### 6. CI/CD (reason:ci_activity)

Feature branch CI failures are noise. Main/master failures need attention.

```bash
<skill-path>/scripts/fetch-notifications.sh ci_activity --all > /tmp/gh_ci.jsonl
cat /tmp/gh_ci.jsonl | \
  <skill-path>/scripts/classify-ci-notifications.sh > /tmp/gh_ci_classified.jsonl
```

- Dismiss feature branch notifications after confirmation
- Present main/master failures for review

```bash
grep '"branch_type": "feature"' /tmp/gh_ci_classified.jsonl | \
  python3 -c "import sys,json; [print(json.loads(l)['id']) for l in sys.stdin]" | \
  <skill-path>/scripts/mark-done.sh
```

## Final Summary

After processing all categories, present a single summary:

```
## Inbox Triage Summary

### Dismissed
- Participating: X merged/closed
- Review Requested: X merged/closed
- CI/CD: X feature branch failures

### Needs Attention
- Assigned: [list]
- Participating (open): [list]
- Mentions: [list with context]
- Team Mentions: [list with context]
- Review Requested (open): [list]
- CI/CD (main/master): [list]
```

## Notes

- **PATCH before DELETE**: `mark-done.sh` tries DELETE first, then falls back to PATCH + DELETE. Older notifications require PATCH (mark as read) before DELETE (mark as Done) will succeed. This is a GitHub API quirk.
- **DELETE vs PATCH**: PATCH alone marks as "read" but the notification stays visible in inbox filters. DELETE marks as "Done" and removes it from the inbox entirely.
- Items that return 404 (deleted PRs, lost repo access) are safe to dismiss — they go to the dismissed pile automatically.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

github-inbox-triage

Directory Structure

SKILL.md

Report

Notice