feat(skill): add inbox-triage skill for notifications toolset

Ship a second bundled skill that walks the agent through systematic
GitHub notifications triage: enumerate with list_notifications,
partition by reason (review_requested / mention / assign /
security_alert — high; author / comment / state_change — medium;
ci_activity / subscribed — low), act on high-priority items, then
dismiss with state "done" or "read" per the skill's rule.

Demonstrates:
- Multiple bundled skills in one server (registry now has two entries).
- Per-skill toolset gating — pull-requests gates on pull_requests,
  inbox-triage gates on the non-default notifications toolset, so
  enabling one does not force the other.
- Cross-skill reference (the inbox-triage workflow points at the
  pull-requests skill when handling review_requested items).
- Skills teaching workflow judgment (priority buckets) that tool
  descriptions alone cannot encode.

Tests cover the symmetric structural checks, per-toolset registration
paths, the multi-skill index.json shape, and the capability declaration
firing on either toolset.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: olaservo

pkg/github/bundled_skills.go

@@ -14,13 +14,21 @@ import (
 // Adding a new server-bundled skill is one entry here plus a //go:embed
 // line in package skills.
 func bundledSkills(inv *inventory.Inventory) *skills.Registry {
-	return skills.New().Add(skills.Bundled{
-		Name:        "pull-requests",
-		Description: "Submit a multi-comment GitHub pull request review using the pending-review workflow. Use when leaving line-specific feedback on a pull request, when asked to review a PR, or whenever creating any review with more than one comment.",
-		Content:     skills.PullRequestsSKILL,
-		Icons:       octicons.Icons("light-bulb"),
-		Enabled:     func() bool { return inv.IsToolsetEnabled(ToolsetMetadataPullRequests.ID) },
-	})
+	return skills.New().
+		Add(skills.Bundled{
+			Name:        "pull-requests",
+			Description: "Submit a multi-comment GitHub pull request review using the pending-review workflow. Use when leaving line-specific feedback on a pull request, when asked to review a PR, or whenever creating any review with more than one comment.",
+			Content:     skills.PullRequestsSKILL,
+			Icons:       octicons.Icons("light-bulb"),
+			Enabled:     func() bool { return inv.IsToolsetEnabled(ToolsetMetadataPullRequests.ID) },
+		}).
+		Add(skills.Bundled{
+			Name:        "inbox-triage",
+			Description: "Systematically triage the current user's GitHub notifications inbox — enumerate unread items, prioritize by notification reason (review requests, mentions, assignments, security alerts), act on the high-priority ones, then dismiss the rest. Use when the user asks \"what should I work on?\", \"catch me up on GitHub\", \"triage my inbox\", \"what needs my attention?\", or otherwise wants to clear their notifications backlog.",
+			Content:     skills.InboxTriageSKILL,
+			Icons:       octicons.Icons("bell"),
+			Enabled:     func() bool { return inv.IsToolsetEnabled(ToolsetMetadataNotifications.ID) },
+		})
 }
 
 // DeclareSkillsExtensionIfEnabled adds the skills-over-MCP extension

pkg/github/bundled_skills_test.go

@@ -13,10 +13,13 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// pullRequestsSkillURI is the canonical URI of the bundled pull-requests
-// skill, derived from the skills.Bundled entry so tests never drift from
-// the single source of truth.
-var pullRequestsSkillURI = skills.Bundled{Name: "pull-requests"}.URI()
+// pullRequestsSkillURI / inboxTriageSkillURI are the canonical URIs of the
+// bundled skills, derived from skills.Bundled so tests never drift from the
+// single source of truth.
+var (
+	pullRequestsSkillURI = skills.Bundled{Name: "pull-requests"}.URI()
+	inboxTriageSkillURI  = skills.Bundled{Name: "inbox-triage"}.URI()
+)
 
 // Test_PullRequestsSkill_EmbeddedContent verifies the SEP structural requirement
 // that the frontmatter `name` field matches the final segment of the skill-path
@@ -50,6 +53,35 @@ func Test_PullRequestsSkill_EmbeddedContent(t *testing.T) {
 	assert.Contains(t, body, "submit_pending", "the distinctive tool method must be present")
 }
 
+// Test_InboxTriageSkill_EmbeddedContent verifies the SEP structural
+// requirements for the inbox-triage skill and that its substantive tool
+// references are preserved.
+func Test_InboxTriageSkill_EmbeddedContent(t *testing.T) {
+	require.NotEmpty(t, skills.InboxTriageSKILL, "SKILL.md must be embedded")
+
+	md := strings.ReplaceAll(skills.InboxTriageSKILL, "\r\n", "\n")
+	require.True(t, strings.HasPrefix(md, "---\n"), "SKILL.md must begin with YAML frontmatter")
+
+	end := strings.Index(md[4:], "\n---\n")
+	require.GreaterOrEqual(t, end, 0, "SKILL.md must have closing frontmatter fence")
+	frontmatter := md[4 : 4+end]
+
+	var frontmatterName string
+	for _, line := range strings.Split(frontmatter, "\n") {
+		if strings.HasPrefix(line, "name:") {
+			frontmatterName = strings.TrimSpace(strings.TrimPrefix(line, "name:"))
+			break
+		}
+	}
+	require.NotEmpty(t, frontmatterName, "SKILL.md frontmatter must declare `name`")
+	assert.Equal(t, "inbox-triage", frontmatterName, "frontmatter name must match final skill-path segment in %s", inboxTriageSkillURI)
+
+	body := md[4+end+5:]
+	assert.Contains(t, body, "## Workflow")
+	assert.Contains(t, body, "list_notifications", "triage workflow must reference list_notifications")
+	assert.Contains(t, body, "dismiss_notification", "triage workflow must reference dismiss_notification")
+}
+
 // Test_BundledSkills_Registration verifies that skill resources are
 // registered when the backing toolset is enabled, and omitted when it is not.
 func Test_BundledSkills_Registration(t *testing.T) {
@@ -87,9 +119,53 @@ func Test_BundledSkills_Registration(t *testing.T) {
 
 		for _, r := range listResources(t, ctx, srv) {
 			assert.NotEqual(t, pullRequestsSkillURI, r.URI)
+			assert.NotEqual(t, inboxTriageSkillURI, r.URI)
 			assert.NotEqual(t, skills.IndexURI, r.URI)
 		}
 	})
+
+	t.Run("registers inbox-triage when notifications toolset enabled", func(t *testing.T) {
+		inv, err := NewInventory(translations.NullTranslationHelper).
+			WithToolsets([]string{string(ToolsetMetadataNotifications.ID)}).
+			Build()
+		require.NoError(t, err)
+
+		srv := mcp.NewServer(&mcp.Implementation{Name: "test"}, &mcp.ServerOptions{
+			Capabilities: &mcp.ServerCapabilities{Resources: &mcp.ResourceCapabilities{}},
+		})
+		RegisterBundledSkills(srv, inv)
+
+		uris := map[string]string{}
+		for _, r := range listResources(t, ctx, srv) {
+			uris[r.URI] = r.MIMEType
+		}
+		assert.Equal(t, "text/markdown", uris[inboxTriageSkillURI])
+		assert.NotContains(t, uris, pullRequestsSkillURI, "only notifications enabled — pull-requests should not be registered")
+		assert.Equal(t, "application/json", uris[skills.IndexURI])
+	})
+
+	t.Run("registers both when both toolsets enabled", func(t *testing.T) {
+		inv, err := NewInventory(translations.NullTranslationHelper).
+			WithToolsets([]string{
+				string(ToolsetMetadataPullRequests.ID),
+				string(ToolsetMetadataNotifications.ID),
+			}).
+			Build()
+		require.NoError(t, err)
+
+		srv := mcp.NewServer(&mcp.Implementation{Name: "test"}, &mcp.ServerOptions{
+			Capabilities: &mcp.ServerCapabilities{Resources: &mcp.ResourceCapabilities{}},
+		})
+		RegisterBundledSkills(srv, inv)
+
+		uris := map[string]struct{}{}
+		for _, r := range listResources(t, ctx, srv) {
+			uris[r.URI] = struct{}{}
+		}
+		assert.Contains(t, uris, pullRequestsSkillURI)
+		assert.Contains(t, uris, inboxTriageSkillURI)
+		assert.Contains(t, uris, skills.IndexURI)
+	})
 }
 
 // Test_BundledSkills_ReadContent verifies that reading the skill resource
@@ -134,6 +210,37 @@ func Test_BundledSkills_ReadContent(t *testing.T) {
 	})
 }
 
+// Test_BundledSkills_Index_MultipleSkills verifies that all enabled skills
+// appear in the discovery index, not just the first one.
+func Test_BundledSkills_Index_MultipleSkills(t *testing.T) {
+	ctx := context.Background()
+	inv, err := NewInventory(translations.NullTranslationHelper).
+		WithToolsets([]string{
+			string(ToolsetMetadataPullRequests.ID),
+			string(ToolsetMetadataNotifications.ID),
+		}).
+		Build()
+	require.NoError(t, err)
+
+	srv := mcp.NewServer(&mcp.Implementation{Name: "test"}, &mcp.ServerOptions{
+		Capabilities: &mcp.ServerCapabilities{Resources: &mcp.ResourceCapabilities{}},
+	})
+	RegisterBundledSkills(srv, inv)
+
+	session := connectClient(t, ctx, srv)
+	res, err := session.ReadResource(ctx, &mcp.ReadResourceParams{URI: skills.IndexURI})
+	require.NoError(t, err)
+
+	var idx skills.IndexDoc
+	require.NoError(t, json.Unmarshal([]byte(res.Contents[0].Text), &idx))
+	names := map[string]string{}
+	for _, s := range idx.Skills {
+		names[s.Name] = s.URL
+	}
+	assert.Equal(t, pullRequestsSkillURI, names["pull-requests"])
+	assert.Equal(t, inboxTriageSkillURI, names["inbox-triage"])
+}
+
 // Test_DeclareSkillsExtensionIfEnabled verifies that the skills-over-MCP
 // extension (SEP-2133) is declared in ServerOptions.Capabilities when the
 // pull_requests toolset is enabled, and is absent when it is not.
@@ -167,6 +274,20 @@ func Test_DeclareSkillsExtensionIfEnabled(t *testing.T) {
 		}
 	})
 
+	t.Run("declares when notifications enabled (any skill triggers declaration)", func(t *testing.T) {
+		inv, err := NewInventory(translations.NullTranslationHelper).
+			WithToolsets([]string{string(ToolsetMetadataNotifications.ID)}).
+			Build()
+		require.NoError(t, err)
+
+		opts := &mcp.ServerOptions{}
+		DeclareSkillsExtensionIfEnabled(opts, inv)
+
+		require.NotNil(t, opts.Capabilities)
+		_, ok := opts.Capabilities.Extensions[skills.ExtensionKey]
+		assert.True(t, ok, "skills extension must be declared when any bundled skill is enabled")
+	})
+
 	t.Run("preserves other extensions already declared", func(t *testing.T) {
 		inv, err := NewInventory(translations.NullTranslationHelper).
 			WithToolsets([]string{string(ToolsetMetadataPullRequests.ID)}).

skills/bundled.go

@@ -14,3 +14,6 @@ import _ "embed"
 
 //go:embed pull-requests/SKILL.md
 var PullRequestsSKILL string
+
+//go:embed inbox-triage/SKILL.md
+var InboxTriageSKILL string

skills/inbox-triage/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: inbox-triage
+description: Systematically triage the current user's GitHub notifications inbox — enumerate unread items, prioritize by notification reason (review requests, mentions, assignments, security alerts), act on the high-priority ones, then dismiss the rest. Use when the user asks "what should I work on?", "catch me up on GitHub", "triage my inbox", "what needs my attention?", or otherwise wants to clear their notifications backlog.
+---
+
+## When to use
+
+Use this skill when the user asks about their GitHub inbox, pending work, or outstanding notifications — any of:
+
+- "What should I work on next?"
+- "Catch me up on GitHub."
+- "Triage my inbox."
+- "What needs my attention?"
+- "Clear my notifications."
+
+## Workflow
+
+1. **Enumerate.** Call `list_notifications` with `filter: "default"` (unread only — the common case). Switch to `filter: "include_read"` only if the user explicitly asks for a full sweep. Pass `since` as an RFC3339 timestamp to scope to recent activity (e.g. the last day or since the last triage).
+
+2. **Partition by `reason`.** Each notification carries a `reason` field. Group into priority buckets:
+
+   - **High — act or respond promptly:**
+     - `review_requested` — someone is waiting on your review.
+     - `mention` / `team_mention` — you were @-referenced.
+     - `assign` — you were assigned an issue or PR.
+     - `security_alert` — security advisory or Dependabot alert.
+   - **Medium — read and decide:**
+     - `author` — updates on threads you opened.
+     - `comment` — replies on threads you participated in.
+     - `state_change` — issue/PR closed or reopened.
+   - **Low — usually safe to mark read without reading:**
+     - `ci_activity` — workflow runs. Look only if you own CI for this repo.
+     - `subscribed` — repo-watch updates on threads you haven't participated in.
+
+3. **Drill in on high-priority.** For each high-priority notification, call `get_notification_details` to inspect the item, then take the appropriate action — leave a review (see the `pull-requests` skill), comment, close, etc.
+
+4. **Dismiss as you go.** After acting on (or deciding to skip) each high-priority item, call `dismiss_notification` with the `threadID` and a `state`:
+   - `state: "done"` archives the notification so it no longer appears in default queries. Use for items you've fully resolved.
+   - `state: "read"` keeps the notification visible but marks it acknowledged. Use for "I've seen this, coming back later."
+
+5. **Bulk-close the noise.** After the high-priority pass, if a large medium/low bucket remains and the user is comfortable, call `mark_all_notifications_read`. Only do this with explicit user approval — a blanket mark-read can bury something the partitioning rules missed.
+
+## Caveats
+
+- **`read` vs `done` matters.** `read` leaves the notification in the default inbox; `done` removes it. Pick intentionally based on whether there's follow-up.
+- **Silence chatty threads.** If one issue/PR is generating a flood, call `manage_notification_subscription` with action `ignore` to silence that specific thread. For an entire noisy repository, use `manage_repository_notification_subscription`.
+- **Surface decisions, don't hide them.** After each bucket, summarize to the user what you acted on, what you dismissed, and what's left open for them. Do not silently mark-read a pile of notifications.
+- **Respect scope.** If the user narrows to a specific repo ("triage my inbox for `owner/repo`"), pass `owner` and `repo` to `list_notifications` rather than filtering client-side after fetching everything.