diff --git a/skills/maintainer-manage/SKILL.md b/skills/maintainer-manage/SKILL.md new file mode 100644 index 0000000..e599ed2 --- /dev/null +++ b/skills/maintainer-manage/SKILL.md @@ -0,0 +1,115 @@ +--- +name: maintainer-manage +description: Work through your GitHub notification inbox — group threads by repo and reason, show what actually needs you, and clear the rest by marking done or unsubscribing. Use when the maintainer asks to triage notifications, clear the inbox, or find what is waiting on them. +disable-model-invocation: true +--- + +# Maintainer Manage + +Notifications are a queue, not a feed. The goal is a short list of things that need the maintainer and an empty rest. + +Work from the notifications API, not email. Email is a copy with worse metadata. + +## 1. Check access + +```sh +gh auth status +gh api rate_limit --jq '.resources.core' +``` + +Notifications need the `notifications` scope. If `gh auth status` does not list it, the fix is: + +```sh +gh auth refresh -s notifications +``` + +Ask before running that; it changes the maintainer's auth. + +## 2. Inventory + +```sh +gh api notifications --paginate +gh api "notifications?all=true&per_page=100" --paginate # include read +gh api "notifications?since=2026-10-01T00:00:00Z" --paginate +``` + +Each thread carries `id`, `reason`, `unread`, `updated_at`, `subject.title`, `subject.type` (`Issue`, `PullRequest`, `Discussion`, `Commit`, `Release`), `subject.url`, and `repository.full_name`. + +Count before reading detail. Do not open every thread to sort it. + +## 3. Sort into three buckets + +| Bucket | Reasons | Meaning | +| --- | --- | --- | +| **Needs you** | `review_requested`, `assign`, `mention`, `team_mention`, `security_alert`, `author`, `state_change` on your work | A person is waiting on you | +| **FYI** | `comment`, `subscribed`, `ci_activity`, `state_change` elsewhere | Read if useful, no action | +| **Trash** | bots, merged or closed threads, stale `subscribed`, org invitations, release noise | Clear it | + +Rules: + +- `author` on your own PR or issue means someone replied to you: needs you. +- `ci_activity` is trash unless the run is on your own branch and it failed. +- A thread whose issue is closed and merged needs no action. +- If unsure, leave it in FYI. Never trash something a person is waiting on. + +## 4. Show the plan + +``` +Needs you (4) + owner/repo PR #123 Fix cursor jump review_requested 2h + owner/repo Issue #98 Crash on empty file mention 1d + +FYI (11) + owner/repo PR #77 Bump deps subscribed 3d + +Trash (37) + 31 bot/release, 4 closed-and-merged, 2 org invites +``` + +Ask before any write. Execute one bucket at a time, starting with Trash, so the list the maintainer looks at afterwards is real. + +## 5. Act + +```sh +# Mark read, keep the thread. +gh api -X PATCH notifications/threads/ + +# Mark done: removes it from the inbox. +gh api -X DELETE notifications/threads/ + +# Stop following, keep the thread accessible. +gh api -X DELETE notifications/threads//subscription + +# Mute a noisy repo entirely. +gh api -X PUT repos/OWNER/REPO/notifications -f ignored=true + +# Check what you are subscribed to. +gh api notifications/threads//subscription +``` + +Mapping: + +- **Needs you**: mark read only. Never `DELETE`. +- **FYI**: mark read; mark done only when the thread is closed. +- **Trash**: mark done. Unsubscribe only when the maintainer wants out of the thread for good. +- **Repo-level noise**: offer a mute; never mute without approval. + +## 6. Report + +``` +Cleared 37 threads: 31 bot/release, 4 closed, 2 invites. +Left 4 needing you: + owner/repo#123 review requested (2h) + owner/repo#98 mention (1d) +Inbox: 11 unread (was 52). +``` + +Link each item in the needs-you list. Nothing else. + +## Guardrails + +- Never mark done something in "needs you". +- Notification ids belong to this user and this session; do not reuse them later. +- `--paginate`, or you will miss threads past the first page. +- Batch writes are fine, but one bucket per approval. +- Surface a security alert first and never clear it.