feat(skills): sync with SEP-2640 upstream b405ba5

Entry resources are now {uri, digest, size} triples, and the resources
field always serializes as an array or the literal string "dynamic".
Enforce the SEP's per-skill limits (512 files, 16 MiB) in skills.New and
pre-check them from tree metadata in RepoSkillEntry before fetching any
blob. Existing-but-empty directories answer with an empty resources
array instead of -32602. The extension's results carry the base
protocol's resultType marker on 2026-07-28+ sessions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ff8YDXkcySZpDBVbHkEtu5

Author: olaservo

pkg/github/skills_dynamic.go

@@ -47,6 +47,25 @@ func RepoSkillEntry(ctx context.Context, uri string) (*skills.Entry, error) {
 		return nil, nil // skill not found in the repository
 	}
 
+	// Enforce the SEP-2640 per-skill limits from the tree metadata before
+	// fetching a single blob, so an oversized skill costs one tree call,
+	// not one fetch per file.
+	var fileCount int
+	var totalBytes int64
+	for _, entry := range entries {
+		if entry.GetType() != "blob" || !strings.HasPrefix(entry.GetPath(), dir+"/") {
+			continue
+		}
+		fileCount++
+		totalBytes += int64(entry.GetSize())
+	}
+	if fileCount > skills.MaxFilesPerSkill || totalBytes > skills.MaxSkillBytes {
+		return nil, &jsonrpc.Error{
+			Code:    jsonrpc.CodeInvalidParams,
+			Message: fmt.Sprintf("skill %q exceeds the SEP-2640 per-skill limits (%d files, %d bytes)", skillName, fileCount, totalBytes),
+		}
+	}
+
 	// Fetch every file in the skill directory and digest its raw bytes.
 	// Skills are small by design (a SKILL.md plus a handful of supporting
 	// files), so one blob fetch per file is acceptable for skills/get,
@@ -135,7 +154,9 @@ func RepoSkillDirectory(ctx context.Context, uri string) ([]*mcp.Resource, error
 		target = dir + "/" + subPath
 	}
 
-	var children []*mcp.Resource
+	// Non-nil so an empty directory answers with an empty resources array
+	// rather than reading as "not a directory this server serves".
+	children := []*mcp.Resource{}
 	targetExists := subPath == "" // the skill root exists by discovery
 	for _, entry := range entries {
 		entryPath := entry.GetPath()

pkg/github/skills_dynamic_test.go

@@ -72,8 +72,32 @@ func Test_RepoSkillEntry(t *testing.T) {
 		require.Len(t, entry.Resources, 2)
 		assert.Equal(t, entry.URI, entry.Resources[0].URI)
 		assert.Equal(t, skills.Digest([]byte(repoSkillMD)), entry.Resources[0].Digest)
+		assert.Equal(t, int64(len(repoSkillMD)), entry.Resources[0].Size)
 		assert.Equal(t, "skill://octocat/hello-world/my-skill/references/GUIDE.md", entry.Resources[1].URI)
 		assert.Equal(t, skills.Digest([]byte(repoGuideMD)), entry.Resources[1].Digest)
+		assert.Equal(t, int64(len(repoGuideMD)), entry.Resources[1].Size)
+	})
+
+	t.Run("-32602 for a skill over the size limit, without fetching blobs", func(t *testing.T) {
+		handlers := repoSkillHandlers(repoSkillMD)
+		handlers[GetReposGitTreesByOwnerByRepoByTree] = func(w http.ResponseWriter, _ *http.Request) {
+			tree := &gogithub.Tree{Entries: []*gogithub.TreeEntry{
+				{Path: gogithub.Ptr("skills/my-skill/SKILL.md"), Type: gogithub.Ptr("blob"), SHA: gogithub.Ptr("sha-skill"), Size: gogithub.Ptr(skills.MaxSkillBytes + 1)},
+			}}
+			data, _ := json.Marshal(tree)
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write(data)
+		}
+		handlers[getReposGitBlobsBySHA] = func(w http.ResponseWriter, _ *http.Request) {
+			t.Fatal("blob fetched for a skill that fails the limit pre-check")
+		}
+		ctx := dynamicTestContext(t, handlers)
+		_, err := RepoSkillEntry(ctx, "skill://octocat/hello-world/my-skill/SKILL.md")
+		require.Error(t, err)
+		var jsonrpcErr *jsonrpc.Error
+		require.ErrorAs(t, err, &jsonrpcErr)
+		assert.EqualValues(t, jsonrpc.CodeInvalidParams, jsonrpcErr.Code)
+		assert.Contains(t, jsonrpcErr.Message, "limit")
 	})
 
 	t.Run("nil for URIs that are not a SKILL.md", func(t *testing.T) {

skills/methods.go

@@ -25,6 +25,27 @@ const (
 // property — digest verification governs content regardless.
 const listTTLMs = 3_600_000
 
+// resultTypeComplete is the base protocol's multi-round-trip result marker
+// (SEP-2322): results on 2026-07-28+ sessions declare themselves "complete".
+// The SDK stamps its own result types automatically but not custom methods',
+// so the extension's handlers set it themselves.
+const (
+	resultTypeComplete      = "complete"
+	protocolVersion20260728 = "2026-07-28"
+)
+
+// completeResultType returns the resultType value for a session: "complete"
+// when the session negotiated 2026-07-28 or later, empty (omitted) for older
+// clients, for which the field does not exist.
+func completeResultType(ss *mcp.ServerSession) string {
+	if ss != nil {
+		if p := ss.InitializeParams(); p != nil && p.ProtocolVersion < protocolVersion20260728 {
+			return ""
+		}
+	}
+	return resultTypeComplete
+}
+
 // ListSkillsParams is the skills/list request payload.
 type ListSkillsParams struct {
 	mcp.ParamsBase
@@ -36,7 +57,10 @@ type ListSkillsParams struct {
 type ListSkillsResult struct {
 	mcp.ResultBase
 	mcp.Cacheable
-	Skills []Entry `json:"skills"`
+	// ResultType is the base protocol's completion marker on 2026-07-28+
+	// sessions; see completeResultType.
+	ResultType string  `json:"resultType,omitempty"`
+	Skills     []Entry `json:"skills"`
 	// NextCursor, when present, indicates more entries are available.
 	NextCursor string `json:"nextCursor,omitempty"`
 }
@@ -52,7 +76,8 @@ type GetSkillParams struct {
 // shape and meaning to an entry of skills/list.
 type GetSkillResult struct {
 	mcp.ResultBase
-	Skill Entry `json:"skill"`
+	ResultType string `json:"resultType,omitempty"`
+	Skill      Entry  `json:"skill"`
 }
 
 // DirectoryReadParams is the resources/directory/read request payload.
@@ -70,7 +95,8 @@ type DirectoryReadParams struct {
 // mimeType "inode/directory".
 type DirectoryReadResult struct {
 	mcp.ResultBase
-	Resources []*mcp.Resource `json:"resources"`
+	ResultType string          `json:"resultType,omitempty"`
+	Resources  []*mcp.Resource `json:"resources"`
 	// NextCursor, when present, indicates more children are available.
 	NextCursor string `json:"nextCursor,omitempty"`
 }
@@ -138,8 +164,8 @@ func serveFile(uri string, f File) mcp.ResourceHandler {
 // so it always fits one page: any cursor is accepted and the full listing
 // returned with no nextCursor, which terminates every conforming pagination
 // loop.
-func (p *Publisher) listSkills(_ context.Context, _ *mcp.ServerSession, _ *ListSkillsParams) (*ListSkillsResult, error) {
-	res := &ListSkillsResult{Skills: p.Registry.Entries()}
+func (p *Publisher) listSkills(_ context.Context, ss *mcp.ServerSession, _ *ListSkillsParams) (*ListSkillsResult, error) {
+	res := &ListSkillsResult{Skills: p.Registry.Entries(), ResultType: completeResultType(ss)}
 	res.TTLMs = listTTLMs
 	res.CacheScope = "public"
 	return res, nil
@@ -148,42 +174,42 @@ func (p *Publisher) listSkills(_ context.Context, _ *mcp.ServerSession, _ *ListS
 // getSkill implements skills/get. Per the SEP it answers for every skill the
 // server serves — listed or not — and returns -32602 (the same code
 // resources/read uses for unknown resources) otherwise.
-func (p *Publisher) getSkill(ctx context.Context, _ *mcp.ServerSession, params *GetSkillParams) (*GetSkillResult, error) {
+func (p *Publisher) getSkill(ctx context.Context, ss *mcp.ServerSession, params *GetSkillParams) (*GetSkillResult, error) {
 	if params == nil || params.URI == "" {
 		return nil, &jsonrpc.Error{Code: jsonrpc.CodeInvalidParams, Message: "missing required parameter: uri"}
 	}
 	if s, ok := p.Registry.Get(params.URI); ok {
-		return &GetSkillResult{Skill: s.Entry()}, nil
+		return &GetSkillResult{Skill: s.Entry(), ResultType: completeResultType(ss)}, nil
 	}
 	if p.DynamicGet != nil {
 		entry, err := p.DynamicGet(ctx, params.URI)
 		if err != nil {
 			return nil, err
 		}
 		if entry != nil {
-			return &GetSkillResult{Skill: *entry}, nil
+			return &GetSkillResult{Skill: *entry, ResultType: completeResultType(ss)}, nil
 		}
 	}
 	return nil, mcp.ResourceNotFoundError(params.URI)
 }
 
 // readDirectory implements resources/directory/read. Like listSkills, bundled
 // directories are small enough to always fit one page.
-func (p *Publisher) readDirectory(ctx context.Context, _ *mcp.ServerSession, params *DirectoryReadParams) (*DirectoryReadResult, error) {
+func (p *Publisher) readDirectory(ctx context.Context, ss *mcp.ServerSession, params *DirectoryReadParams) (*DirectoryReadResult, error) {
 	if params == nil || params.URI == "" {
 		return nil, &jsonrpc.Error{Code: jsonrpc.CodeInvalidParams, Message: "missing required parameter: uri"}
 	}
 	uri := strings.TrimSuffix(params.URI, "/")
 	if children, ok := p.Registry.Directory(uri); ok {
-		return &DirectoryReadResult{Resources: children}, nil
+		return &DirectoryReadResult{Resources: children, ResultType: completeResultType(ss)}, nil
 	}
 	if p.DynamicDirectoryRead != nil {
 		children, err := p.DynamicDirectoryRead(ctx, uri)
 		if err != nil {
 			return nil, err
 		}
 		if children != nil {
-			return &DirectoryReadResult{Resources: children}, nil
+			return &DirectoryReadResult{Resources: children, ResultType: completeResultType(ss)}, nil
 		}
 	}
 	return nil, mcp.ResourceNotFoundError(params.URI)

skills/methods_test.go

@@ -78,6 +78,7 @@ func TestSkillsListOverProtocol(t *testing.T) {
 	assert.Empty(t, res.NextCursor, "an entry is atomic and the catalog fits one page")
 	assert.Positive(t, res.TTLMs)
 	assert.Equal(t, "public", res.CacheScope)
+	assert.Equal(t, "complete", res.ResultType)
 
 	// Each SKILL.md listed is readable via plain resources/read, and its
 	// content matches the advertised digest.
@@ -87,6 +88,7 @@ func TestSkillsListOverProtocol(t *testing.T) {
 		require.Len(t, rr.Contents, 1)
 		sum := sha256.Sum256([]byte(rr.Contents[0].Text))
 		assert.Equal(t, entry.Resources[0].Digest, "sha256:"+hex.EncodeToString(sum[:]))
+		assert.Equal(t, int64(len(rr.Contents[0].Text)), entry.Resources[0].Size)
 
 		// Frontmatter identity requirement: a host parsing the fetched
 		// SKILL.md must find frontmatter identical to the entry's.
@@ -108,6 +110,7 @@ func TestSkillsGetOverProtocol(t *testing.T) {
 		assert.Equal(t, "skill://acme/pdf-processing/SKILL.md", res.Skill.URI)
 		assert.Equal(t, "pdf-processing", res.Skill.Frontmatter["name"])
 		assert.Len(t, res.Skill.Resources, 6)
+		assert.Equal(t, "complete", res.ResultType)
 	})
 
 	t.Run("unknown skill is -32602", func(t *testing.T) {
@@ -134,6 +137,7 @@ func TestDirectoryReadOverProtocol(t *testing.T) {
 			&skills.DirectoryReadParams{URI: "skill://acme/pdf-processing/templates"})
 		require.NoError(t, err)
 		require.Len(t, res.Resources, 3)
+		assert.Equal(t, "complete", res.ResultType)
 		assert.Equal(t, "regional", res.Resources[2].Name)
 		assert.Equal(t, skills.DirectoryMIMEType, res.Resources[2].MIMEType)
 
@@ -183,7 +187,9 @@ func TestDynamicHooks(t *testing.T) {
 	dynamicEntry := skills.Entry{
 		URI:         "skill://dyn/generated/SKILL.md",
 		Frontmatter: map[string]any{"name": "generated", "description": "made on demand"},
-		// No resources: dynamically generated content cannot be pre-digested.
+		// Dynamically generated content cannot be pre-digested; the entry's
+		// resources field serializes as the string "dynamic".
+		Dynamic: true,
 	}
 	cs := connect(t, testFS, "acme", func(p *skills.Publisher) {
 		p.DynamicGet = func(_ context.Context, uri string) (*skills.Entry, error) {
@@ -206,6 +212,8 @@ func TestDynamicHooks(t *testing.T) {
 			ctx, cs, skills.MethodSkillsGet, &skills.GetSkillParams{URI: dynamicEntry.URI})
 		require.NoError(t, err)
 		assert.Equal(t, dynamicEntry.URI, res.Skill.URI)
+		// The "dynamic" marker survives the wire roundtrip.
+		assert.True(t, res.Skill.Dynamic)
 		assert.Empty(t, res.Skill.Resources)
 	})
 

skills/skill.go

@@ -14,6 +14,7 @@ import (
 	"bytes"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"mime"
 	"path"
@@ -36,6 +37,12 @@ const (
 	// DirectoryMIMEType marks directory resources in
 	// resources/directory/read listings.
 	DirectoryMIMEType = "inode/directory"
+
+	// MaxFilesPerSkill and MaxSkillBytes are the SEP-2640 per-skill limits:
+	// conforming hosts must accept skills up to these bounds, and servers
+	// should not serve skills beyond them.
+	MaxFilesPerSkill = 512
+	MaxSkillBytes    = 16 * 1024 * 1024
 )
 
 // File is a single file of a skill, addressed relative to the skill directory.
@@ -80,29 +87,84 @@ func (s *Skill) RootURI() string { return "skill://" + s.Path }
 // FileURI returns the resource URI of a file within the skill directory.
 func (s *Skill) FileURI(relPath string) string { return "skill://" + s.Path + "/" + relPath }
 
-// EntryResource is one {uri, digest} pair of a skill entry's resources set.
+// EntryResource is one {uri, digest, size} triple of a skill entry's
+// resources set.
 type EntryResource struct {
 	URI    string `json:"uri"`
 	Digest string `json:"digest"`
+	// Size is the length in bytes of the file's raw content — the same
+	// bytes the digest covers.
+	Size int64 `json:"size"`
 }
 
 // Entry is a skill entry as carried by skills/list and skills/get results.
+// The wire `resources` field is required and is either the Resources array
+// or the literal string "dynamic" (when Dynamic is set); an entry with
+// neither is invalid and hosts will not load it.
 type Entry struct {
 	// URI is the resource URI of the skill's SKILL.md.
 	URI string `json:"uri"`
 	// Frontmatter is the SKILL.md YAML frontmatter rendered verbatim as JSON.
 	Frontmatter map[string]any `json:"frontmatter"`
-	// Resources enumerates every file of the skill with its digest — the unit
-	// of content a host verifies and binds approval to. Omitted only for
-	// dynamically generated skills that cannot publish stable digests.
-	Resources []EntryResource `json:"resources,omitempty"`
+	// Resources enumerates every file of the skill with its digest and size —
+	// the unit of content a host verifies and binds approval to.
+	Resources []EntryResource `json:"resources"`
+	// Dynamic marks a skill whose content is generated on demand and cannot
+	// publish stable digests. When set, `resources` serializes as the string
+	// "dynamic" and Resources is ignored.
+	Dynamic bool `json:"-"`
+}
+
+// entryWire is Entry's JSON shape; resources holds an array or "dynamic".
+type entryWire struct {
+	URI         string          `json:"uri"`
+	Frontmatter map[string]any  `json:"frontmatter"`
+	Resources   json.RawMessage `json:"resources"`
+}
+
+func (e Entry) MarshalJSON() ([]byte, error) {
+	w := entryWire{URI: e.URI, Frontmatter: e.Frontmatter}
+	if e.Dynamic {
+		w.Resources = json.RawMessage(`"dynamic"`)
+	} else {
+		resources := e.Resources
+		if resources == nil {
+			resources = []EntryResource{}
+		}
+		b, err := json.Marshal(resources)
+		if err != nil {
+			return nil, err
+		}
+		w.Resources = b
+	}
+	return json.Marshal(w)
+}
+
+func (e *Entry) UnmarshalJSON(data []byte) error {
+	var w entryWire
+	if err := json.Unmarshal(data, &w); err != nil {
+		return err
+	}
+	*e = Entry{URI: w.URI, Frontmatter: w.Frontmatter}
+	if len(w.Resources) == 0 {
+		return nil
+	}
+	if bytes.Equal(bytes.TrimSpace(w.Resources), []byte(`"dynamic"`)) {
+		e.Dynamic = true
+		return nil
+	}
+	return json.Unmarshal(w.Resources, &e.Resources)
 }
 
 // Entry returns the skill's wire entry.
 func (s *Skill) Entry() Entry {
 	resources := make([]EntryResource, 0, len(s.Files))
 	for _, f := range s.Files {
-		resources = append(resources, EntryResource{URI: s.FileURI(f.Path), Digest: f.Digest})
+		resources = append(resources, EntryResource{
+			URI:    s.FileURI(f.Path),
+			Digest: f.Digest,
+			Size:   int64(len(f.Content)),
+		})
 	}
 	return Entry{URI: s.URI(), Frontmatter: s.Frontmatter, Resources: resources}
 }
@@ -150,6 +212,17 @@ func New(skillPath string, files []File) (*Skill, error) {
 	slices.SortFunc(sorted, func(a, b File) int { return strings.Compare(a.Path, b.Path) })
 	ordered := append([]File{*skillMD}, sorted...)
 
+	if len(ordered) > MaxFilesPerSkill {
+		return nil, fmt.Errorf("skill %q: %d files exceeds the SEP-2640 limit of %d", skillPath, len(ordered), MaxFilesPerSkill)
+	}
+	var totalBytes int64
+	for _, f := range ordered {
+		totalBytes += int64(len(f.Content))
+	}
+	if totalBytes > MaxSkillBytes {
+		return nil, fmt.Errorf("skill %q: %d bytes exceeds the SEP-2640 limit of %d", skillPath, totalBytes, MaxSkillBytes)
+	}
+
 	fm, err := ParseFrontmatter(skillMD.Content)
 	if err != nil {
 		return nil, fmt.Errorf("skill %q: %w", skillPath, err)