feat(skills): add per-repo MCP resource template + skills toolset

Adds the SEP-2640-aligned per-repo Agent Skills surface: a single
parameterized MCP resource template that lets any GitHub repo expose
its skills/ directory through the same skill:// URI scheme used for
bundled skills.

Template:
  skill://{owner}/{repo}/{skill_name}/{+file_path}

`{+file_path}` is RFC 6570 reserved expansion, so a multi-segment
relative path inside the skill directory (e.g. references/GUIDE.md)
round-trips through the template as a single value. SKILL.md and any
relative references mentioned inside it both resolve via this one
template handler.

Discovery on the server:
- Recognizes the four agentskills.io directory conventions:
  skills/<name>/SKILL.md, skills/<namespace>/<name>/SKILL.md,
  plugins/<plugin>/skills/<name>/SKILL.md, and root-level
  <name>/SKILL.md (excluding hidden + convention-prefix dirs).
- Skill discovery happens at request time via the Git Trees API.
- skill:// completion is wired through CompletionsHandler so MCP
  hosts can offer interactive autocomplete on owner/repo/skill_name.

Index integration:
- skills.Registry extended with BundledTemplate + AddTemplate +
  EnabledTemplates so skill://index.json now publishes both
  type:"skill-md" entries (the 27 bundled skills) and a single
  type:"mcp-resource-template" entry (the per-repo template).
- IndexEntry.Name is now omitempty since the SEP example shows
  template entries without a name.
- DeclareCapability fires for either type of entry being enabled.

Toolset gating:
- New non-default `skills` toolset gates the per-repo template's
  index entry. With --toolsets=default the per-repo surface is hidden;
  with --toolsets=default,skills (or --toolsets=all) it's published.
- The per-repo template is defined in pkg/github/skills_resource.go;
  registered via AllResources so the inventory wires it up alongside
  repo:// templates.

Adapted from the resource-template work in
#2129. The non-SEP _manifest endpoint from
that PR is intentionally NOT ported — multi-file skill discovery is
handled by the SEP's per-file URI resolution, not a manifest JSON.

Tests cover: template definition, file handler with SKILL.md, file
handler with multi-segment relative path, missing-arg errors, path
traversal rejection, agentskills.io convention discovery,
URI parsing, completion handler, and the index-entry presence/absence
based on toolset gating.

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

Author: olaservo

pkg/github/bundled_skills.go

@@ -13,9 +13,14 @@ import (
 // The Registry's `Enabled` closure is still available for future use
 // (e.g. feature-flagging a skill behind an experimental toolset).
 //
+// In addition to the bundled SKILL.md catalogue, the registry advertises
+// the per-repo skill resource template (skill://{owner}/{repo}/{skill_name}/{+file_path})
+// in the discovery index when the `skills` toolset is enabled. The matching
+// MCP resource template + handler are registered via the inventory.
+//
 // Adding a new server-bundled skill is one entry here plus a //go:embed
 // line in package skills.
-func bundledSkills(_ *inventory.Inventory) *skills.Registry {
+func bundledSkills(inv *inventory.Inventory) *skills.Registry {
 	return skills.New().
 		Add(skills.Bundled{
 			Name:        "review-pr",
@@ -151,6 +156,14 @@ func bundledSkills(_ *inventory.Inventory) *skills.Registry {
 			Name:        "share-snippet",
 			Description: "Create and manage code snippets via GitHub Gists. Use when sharing a code snippet, creating a quick paste, saving notes as a gist, or managing your existing gists.",
 			Content:     skills.ShareSnippetSKILL,
+		}).
+		// Per-repo skill template (SEP-2640 mcp-resource-template entry).
+		// Gated on the `skills` toolset since the matching MCP resource
+		// template is registered there too.
+		AddTemplate(skills.BundledTemplate{
+			Description: "Agent Skills hosted in any GitHub repository — fill in {owner}/{repo}/{skill_name} to read SKILL.md, then extend the URI to read referenced files (e.g. references/GUIDE.md).",
+			URL:         SkillResourceDiscoveryURL,
+			Enabled:     func() bool { return inv.IsToolsetEnabled(ToolsetMetadataSkills.ID) },
 		})
 }
 

pkg/github/bundled_skills_test.go

@@ -242,6 +242,69 @@ func Test_DeclareSkillsExtensionIfEnabled(t *testing.T) {
 	})
 }
 
+// Test_BundledSkills_TemplateInIndex_WhenSkillsToolsetEnabled verifies that
+// enabling the `skills` toolset causes the per-repo skill template entry to
+// appear in `skill://index.json` with `type: "mcp-resource-template"`. This
+// is the SEP-2640 discovery story for parameterized skill families.
+func Test_BundledSkills_TemplateInIndex_WhenSkillsToolsetEnabled(t *testing.T) {
+	ctx := context.Background()
+	inv, err := NewInventory(translations.NullTranslationHelper).
+		WithToolsets([]string{string(ToolsetMetadataSkills.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))
+
+	var found *skills.IndexEntry
+	for i := range idx.Skills {
+		if idx.Skills[i].Type == "mcp-resource-template" {
+			found = &idx.Skills[i]
+			break
+		}
+	}
+	require.NotNil(t, found, "index must include an mcp-resource-template entry when skills toolset is enabled")
+	assert.Equal(t, SkillResourceDiscoveryURL, found.URL)
+	assert.Empty(t, found.Name, "mcp-resource-template entries omit `name` per SEP example")
+	assert.NotEmpty(t, found.Description)
+}
+
+// Test_BundledSkills_TemplateAbsent_WhenSkillsToolsetDisabled verifies that
+// without the `skills` toolset, the template is not advertised — but the
+// always-on bundled skills still are.
+func Test_BundledSkills_TemplateAbsent_WhenSkillsToolsetDisabled(t *testing.T) {
+	ctx := context.Background()
+	inv, err := NewInventory(translations.NullTranslationHelper).
+		WithToolsets([]string{string(ToolsetMetadataContext.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))
+
+	for _, entry := range idx.Skills {
+		assert.NotEqual(t, "mcp-resource-template", entry.Type, "template entry must not appear when skills toolset disabled")
+	}
+}
+
 // Test_BundledSkills_NoDuplicateURIs guards against accidental duplicate
 // registrations — two skills with the same name would collide on the same
 // skill://github/<name>/SKILL.md URI.

pkg/github/resources.go

@@ -15,5 +15,9 @@ func AllResources(t translations.TranslationHelperFunc) []inventory.ServerResour
 		GetRepositoryResourceCommitContent(t),
 		GetRepositoryResourceTagContent(t),
 		GetRepositoryResourcePrContent(t),
+
+		// Skill resources (SEP-2640): per-file template for any skill in any GitHub repo.
+		// Gated on the `skills` toolset.
+		GetSkillResourceFile(t),
 	}
 }

pkg/github/server.go

@@ -219,6 +219,9 @@ func CompletionsHandler(getClient GetClientFn) func(ctx context.Context, req *mc
 			if strings.HasPrefix(req.Params.Ref.URI, "repo://") {
 				return RepositoryResourceCompletionHandler(getClient)(ctx, req)
 			}
+			if strings.HasPrefix(req.Params.Ref.URI, "skill://") {
+				return SkillResourceCompletionHandler(getClient)(ctx, req)
+			}
 			return nil, fmt.Errorf("unsupported resource URI: %s", req.Params.Ref.URI)
 		case "ref/prompt":
 			return nil, nil