feat(skills): publish skill://index.json and advertise skills extension

Adds SEP-2640 skill discovery so skill-aware MCP clients can enumerate the
server's skills (and the tools each governs) from a single resource read,
without first fetching every SKILL.md.

- Register a `skill://index.json` resource whose handler emits the Agent Skills
  discovery index built from the in-memory skill set. Each entry carries
  `type: skill-md`, `name`, `description`, `url` (the skill's SKILL.md), and the
  skill's `allowedTools`, so clients can gate/defer those tools before loading
  the skill.
- Advertise the `io.modelcontextprotocol/skills` capability extension in the
  server's initialize result. Only the extension is set on ServerOptions, so the
  SDK still infers tools/resources/prompts capabilities from registered handlers.
- Tests: index builder shape + an end-to-end in-memory initialize asserting the
  extension is advertised (without clobbering tools/resources) and index.json
  serves the discovery shape.

Verified against the runtime SEP-2640 consumer: all 27 skills are discovered
with their allowed-tools lists.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/github/server.go

@@ -100,6 +100,14 @@ func NewMCPServer(ctx context.Context, cfg *MCPServerConfig, deps ToolDependenci
 		}
 	}
 
+	// Advertise the skills extension (SEP-2640) so skill-aware clients use skill:// discovery
+	// (skill://index.json + per-skill SKILL.md). Adding only the extension leaves Tools/Resources/
+	// Prompts nil so the SDK still infers them from the registered handlers (see Server.capabilities).
+	if serverOpts.Capabilities == nil {
+		serverOpts.Capabilities = &mcp.ServerCapabilities{}
+	}
+	serverOpts.Capabilities.AddExtension(skillsExtensionID, nil)
+
 	ghServer := NewServer(cfg.Version, cfg.Translator("SERVER_NAME", "github-mcp-server"), cfg.Translator("SERVER_TITLE", "GitHub MCP Server"), serverOpts)
 
 	// Add middlewares. Order matters - for example, the error context middleware should be applied last so that it runs FIRST (closest to the handler) to ensure all errors are captured,

pkg/github/skill_resources.go

@@ -2,12 +2,70 @@ package github
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"strings"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
+// skillsExtensionID is the MCP capabilities extension key (SEP-2640) that signals a server
+// publishes a skill discovery index. Clients that recognise it read skillIndexURI to enumerate
+// skills and the tools each one governs without first fetching every SKILL.md.
+const skillsExtensionID = "io.modelcontextprotocol/skills"
+
+// skillIndexURI is the well-known resource enumerating the server's skills (SEP-2640).
+const skillIndexURI = "skill://index.json"
+
+// skillIndexSchema is the Agent Skills discovery-index schema URI advertised in index.json.
+const skillIndexSchema = "https://schemas.agentskills.io/discovery/0.2.0/index.json"
+
+// skillIndexEntry is one entry in the skill discovery index. `allowedTools` is an additive
+// (passthrough) hint, so SEP-2640-aware clients can gate/defer those tools before a skill is
+// loaded WITHOUT first fetching SKILL.md frontmatter.
+type skillIndexEntry struct {
+	Type         string   `json:"type"`
+	Name         string   `json:"name"`
+	Description  string   `json:"description"`
+	URL          string   `json:"url"`
+	AllowedTools []string `json:"allowedTools"`
+}
+
+// skillIndexDocument is the full `skill://index.json` payload.
+type skillIndexDocument struct {
+	Schema string            `json:"$schema"`
+	Skills []skillIndexEntry `json:"skills"`
+}
+
+// buildSkillIndex constructs the SEP-2640 discovery index from the in-memory skill set. Each entry
+// points at the skill's individually readable SKILL.md resource and carries its allowed-tools list.
+func buildSkillIndex() skillIndexDocument {
+	skills := allSkills()
+	doc := skillIndexDocument{
+		Schema: skillIndexSchema,
+		Skills: make([]skillIndexEntry, 0, len(skills)),
+	}
+	for _, skill := range skills {
+		doc.Skills = append(doc.Skills, skillIndexEntry{
+			Type:         "skill-md",
+			Name:         skill.name,
+			Description:  skill.description,
+			URL:          fmt.Sprintf("skill://github/%s/SKILL.md", skill.name),
+			AllowedTools: skill.allowedTools,
+		})
+	}
+	return doc
+}
+
+// buildSkillIndexJSON serialises the discovery index returned by skill://index.json.
+func buildSkillIndexJSON() (string, error) {
+	body, err := json.MarshalIndent(buildSkillIndex(), "", "  ")
+	if err != nil {
+		return "", fmt.Errorf("marshal skill index: %w", err)
+	}
+	return string(body), nil
+}
+
 // skillDefinition holds the metadata and content for a single skill resource.
 type skillDefinition struct {
 	// name is the skill identifier used in frontmatter and URI
@@ -509,6 +567,33 @@ func buildSkillContent(skill skillDefinition) string {
 // Each skill is a static resource with a skill:// URI that can be discovered
 // by MCP clients supporting the skills pattern.
 func RegisterSkillResources(s *mcp.Server) {
+	// Publish the discovery index first so SEP-2640 clients can enumerate skills (and the tools
+	// each governs) from a single resource read, without fetching every SKILL.md.
+	s.AddResource(
+		&mcp.Resource{
+			URI:         skillIndexURI,
+			Name:        "skill-index",
+			Title:       "Skill index",
+			Description: "SEP-2640 skill discovery index enumerating available skills and their allowed tools.",
+			MIMEType:    "application/json",
+		},
+		func(_ context.Context, _ *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+			body, err := buildSkillIndexJSON()
+			if err != nil {
+				return nil, err
+			}
+			return &mcp.ReadResourceResult{
+				Contents: []*mcp.ResourceContents{
+					{
+						URI:      skillIndexURI,
+						MIMEType: "application/json",
+						Text:     body,
+					},
+				},
+			}, nil
+		},
+	)
+
 	for _, skill := range allSkills() {
 		content := buildSkillContent(skill)
 		uri := fmt.Sprintf("skill://github/%s/SKILL.md", skill.name)

pkg/github/skill_resources_test.go

@@ -1,8 +1,12 @@
 package github
 
 import (
+	"context"
+	"encoding/json"
+	"strings"
 	"testing"
 
+	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -82,3 +86,113 @@ func TestRegisterSkillResources(t *testing.T) {
 	skills := allSkills()
 	assert.Equal(t, 27, len(skills), "expected 27 workflow-oriented skills")
 }
+
+func TestBuildSkillIndex(t *testing.T) {
+	doc := buildSkillIndex()
+
+	assert.Equal(t, skillIndexSchema, doc.Schema)
+	assert.True(t, strings.HasPrefix(doc.Schema, "https://schemas.agentskills.io/discovery/"),
+		"schema must use the Agent Skills discovery prefix the runtime gates on")
+
+	skills := allSkills()
+	require.Len(t, doc.Skills, len(skills), "index must contain one entry per skill")
+
+	byName := make(map[string]skillIndexEntry, len(doc.Skills))
+	for _, entry := range doc.Skills {
+		assert.Equal(t, "skill-md", entry.Type, "entry %q must be type skill-md", entry.Name)
+		assert.Equal(t, "skill://github/"+entry.Name+"/SKILL.md", entry.URL,
+			"entry %q url must point at its registered SKILL.md resource", entry.Name)
+		assert.NotEmpty(t, entry.Description, "entry %q must carry a description", entry.Name)
+		assert.NotEmpty(t, entry.AllowedTools, "entry %q must advertise its allowed tools", entry.Name)
+		byName[entry.Name] = entry
+	}
+
+	// Every skill's allow-list must round-trip into the index so clients can defer those tools
+	// without first fetching SKILL.md.
+	for _, skill := range skills {
+		entry, ok := byName[skill.name]
+		require.True(t, ok, "skill %q missing from index", skill.name)
+		assert.Equal(t, skill.allowedTools, entry.AllowedTools)
+	}
+}
+
+func TestBuildSkillIndexJSON_IsValid(t *testing.T) {
+	body, err := buildSkillIndexJSON()
+	require.NoError(t, err)
+
+	var parsed skillIndexDocument
+	require.NoError(t, json.Unmarshal([]byte(body), &parsed), "index.json must be valid JSON")
+	assert.Equal(t, skillIndexSchema, parsed.Schema)
+	assert.Equal(t, len(allSkills()), len(parsed.Skills))
+}
+
+// TestSkillsExtensionAndIndexAdvertised verifies the SEP-2640 wire contract end-to-end: the server
+// advertises the skills extension in its initialize capabilities and serves skill://index.json with
+// the discovery shape skill-aware clients consume.
+func TestSkillsExtensionAndIndexAdvertised(t *testing.T) {
+	t.Parallel()
+
+	cfg := MCPServerConfig{
+		Version:           "test",
+		Token:             "test-token",
+		EnabledToolsets:   []string{"context"},
+		Translator:        translations.NullTranslationHelper,
+		ContentWindowSize: 5000,
+	}
+	deps := stubDeps{obsv: stubExporters()}
+	inv, err := NewInventory(cfg.Translator).
+		WithDeprecatedAliases(DeprecatedToolAliases).
+		WithToolsets(cfg.EnabledToolsets).
+		Build()
+	require.NoError(t, err)
+
+	srv, err := NewMCPServer(context.Background(), &cfg, deps, inv)
+	require.NoError(t, err)
+
+	st, ct := mcp.NewInMemoryTransports()
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client"}, nil)
+
+	type connResult struct {
+		session *mcp.ClientSession
+		err     error
+	}
+	connCh := make(chan connResult, 1)
+	go func() {
+		cs, cerr := client.Connect(context.Background(), ct, nil)
+		connCh <- connResult{session: cs, err: cerr}
+	}()
+
+	ss, err := srv.Connect(context.Background(), st, nil)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = ss.Close() })
+
+	got := <-connCh
+	require.NoError(t, got.err)
+	require.NotNil(t, got.session)
+	t.Cleanup(func() { _ = got.session.Close() })
+
+	// 1. The skills extension must be advertised so SEP-2640 clients opt into skill:// discovery.
+	init := got.session.InitializeResult()
+	require.NotNil(t, init)
+	require.NotNil(t, init.Capabilities)
+	require.Contains(t, init.Capabilities.Extensions, skillsExtensionID,
+		"server must advertise the skills extension")
+	// Tools/resources must still be inferred — advertising the extension must not clobber them.
+	assert.NotNil(t, init.Capabilities.Tools, "tools capability must still be advertised")
+	assert.NotNil(t, init.Capabilities.Resources, "resources capability must still be advertised")
+
+	// 2. skill://index.json must serve the discovery index.
+	res, err := got.session.ReadResource(context.Background(), &mcp.ReadResourceParams{URI: skillIndexURI})
+	require.NoError(t, err)
+	require.Len(t, res.Contents, 1)
+	assert.Equal(t, "application/json", res.Contents[0].MIMEType)
+
+	var index skillIndexDocument
+	require.NoError(t, json.Unmarshal([]byte(res.Contents[0].Text), &index))
+	assert.True(t, strings.HasPrefix(index.Schema, "https://schemas.agentskills.io/discovery/"))
+	require.Len(t, index.Skills, len(allSkills()))
+	for _, entry := range index.Skills {
+		assert.Equal(t, "skill-md", entry.Type)
+		assert.NotEmpty(t, entry.AllowedTools)
+	}
+}