skills

package
v0.74.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package skills holds the wire types and pure rules for skills served by an upstream MCP server through the io.modelcontextprotocol/skills extension. It is a leaf: every layer may import it, and it imports no other package of this module.

Index

Constants

View Source
const (
	MaxFilesPerSkill   = 512
	MaxSkillBytes      = 16 << 20
	MaxSkillsPerServer = 200
	// MaxUnlistedSkillsPerServer bounds the records kept for skills a server
	// no longer lists, so a server that keeps renaming its skills cannot grow
	// the store. Blocked records are kept beyond it.
	MaxUnlistedSkillsPerServer = 200
	MaxListPages               = 50
	MaxListResponseBytes       = 4 << 20
	// MaxListBytes bounds all pages of one listing together.
	MaxListBytes           = 16 << 20
	MaxStoredTextPerServer = 64 << 20
	MaxReadPerRefresh      = 256 << 20
	MaxFrontmatterBytes    = 64 << 10
	MaxScanBytesPerSkill   = 1 << 20
	MaxURIBytes            = 2048
)

Bounds that keep one upstream from making mcpproxy read, store or scan without limit. They are constants, not config, so every layer agrees.

View Source
const (
	BoundPages         = "pages"
	BoundEntries       = "entries"
	BoundResponseBytes = "response_bytes"
)

The bound that cut a listing short.

View Source
const (
	ReasonInvalidURI          = "invalid_uri"
	ReasonNameMismatch        = "name_mismatch"
	ReasonDynamic             = "dynamic"
	ReasonTooManyFiles        = "too_many_files"
	ReasonTooLarge            = "too_large"
	ReasonServerBoundExceeded = "server_bound_exceeded"
	ReasonUnsupportedDigest   = "unsupported_digest"
	ReasonDigestMismatch      = "digest_mismatch"
	ReasonSizeMismatch        = "size_mismatch"
	ReasonFrontmatterMismatch = "frontmatter_mismatch"
	ReasonFrontmatterInvalid  = "frontmatter_invalid"
	ReasonReadFailed          = "read_failed"
	ReasonStoredCopyDamaged   = "stored_copy_damaged"
)

Reasons a skill cannot be used. They are stored and shown, so they are a stable vocabulary.

View Source
const ExtensionKey = "io.modelcontextprotocol/skills"

ExtensionKey is the capabilities.extensions key an upstream announces to say it serves skills (SEP-2640).

Variables

View Source
var (
	// ErrChunkOffsetPastEnd: the offset is negative or beyond the end of the data.
	ErrChunkOffsetPastEnd = errors.New("offset is past the end of the file")
	// ErrChunkOffsetInsideRune: the offset points into the middle of a UTF-8 character.
	ErrChunkOffsetInsideRune = errors.New("offset is inside a UTF-8 character")
)
View Source
var ErrNotServed = errors.New("skills: the server is not asked for skills")

ErrNotServed is returned by a listing that was not sent: the server does not announce skills, or it is excluded from them. It is deliberately not an empty listing. An empty listing says "this server has no skills now" and unlists what was known; a server that was not asked says nothing.

View Source
var ErrStopped = errors.New("skills: the read was stopped by its caller")

ErrStopped is returned by a multi-request read that its caller's continue check stopped. It is not a failure of the upstream.

Functions

func Chunk

func Chunk(data []byte, offset, limit int64) (text []byte, next int64, more bool, err error)

Chunk cuts at most limit bytes of data starting at byte offset, ending on a UTF-8 character boundary, so the answer can be a few bytes shorter than limit. A limit smaller than one character still returns that whole character, so a reader always makes progress. next is the offset to ask for next (the end of the chunk) and more reports whether data remains after it.

An offset equal to len(data) is valid and returns an empty chunk. An offset beyond the end or inside a character is refused with ErrChunkOffsetPastEnd or ErrChunkOffsetInsideRune. limit must be positive; callers validate it.

func ContentHash

func ContentHash(e Entry) (string, error)

ContentHash returns the approval binding of a skill: sk1- plus the sha256 of an unambiguous encoding of the skill URI, every file (sorted by URI) as (URI, relative path, digest, size), and the canonical frontmatter encoding. Every string is length-prefixed so two different inputs never share an encoding.

func FrontmatterEqual

func FrontmatterEqual(listed, parsed map[string]any) bool

FrontmatterEqual compares the listed frontmatter with the one parsed from SKILL.md by value: YAML and JSON numbers compare by their exact numeric value, nested maps of either origin compare key by key. A value with no canonical form never compares equal.

func ParseFrontmatter

func ParseFrontmatter(skillMD []byte) (map[string]any, error)

ParseFrontmatter reads the leading "---" YAML block of a SKILL.md. The block is bounded at MaxFrontmatterBytes and must be a mapping.

func ParseSkillURI

func ParseSkillURI(uri string) (root, path, name string, err error)

ParseSkillURI splits a skill address. The address must end in /SKILL.md; root is the address without that suffix, path is the root without scheme and "//", and name is the last segment of path.

func RelPath

func RelPath(root, fileURI string) (string, error)

RelPath returns where fileURI sits inside the skill rooted at root. It rejects anything that is not strictly below root: another scheme or host, a query or fragment, an encoded separator or dot segment, an escaping "..", an absolute path, an empty segment or a control character.

func ShouldContinue

func ShouldContinue(ctx context.Context) bool

ShouldContinue reports whether the read may send its next request. A context without a check always may.

func WithContinueCheck

func WithContinueCheck(ctx context.Context, check func() bool) context.Context

WithContinueCheck attaches a check that a multi-request read asks before every request it sends. It is how the catalog stops a listing that is still paging when skills are switched off: a context alone would need someone to watch the configuration and cancel it.

Types

type Entry

type Entry struct {
	URI         string
	Frontmatter map[string]any
	Files       []FileRef
	// Dynamic is set when the server declares resources as "dynamic": the
	// file set cannot be pinned, so the skill is unusable.
	Dynamic bool
}

Entry is one skill as listed by skills/list or returned by skills/get.

func DecodeEntry

func DecodeEntry(raw json.RawMessage) (Entry, error)

DecodeEntry decodes one wire entry. Unknown fields are ignored.

func DecodeGetResult

func DecodeGetResult(raw json.RawMessage) (Entry, error)

DecodeGetResult decodes a skills/get result.

func (Entry) Validate

func (e Entry) Validate() *UnusableError

Validate applies the rules a listed skill must meet before anything is read for it. It returns nil for a usable entry.

type EntryError

type EntryError struct {
	Index int
	URI   string
	Err   error
}

EntryError is a listing entry that did not decode.

type FileRef

type FileRef struct {
	URI    string `json:"uri"`
	Digest string `json:"digest"`
	Size   int64  `json:"size"`
}

FileRef is one file the listing promises, with the digest and size the bytes must match.

type ListPage

type ListPage struct {
	Entries    []Entry
	Errors     []EntryError
	NextCursor string
}

ListPage is one decoded skills/list result. A malformed entry lands in Errors and does not fail the page.

func DecodeListResult

func DecodeListResult(raw json.RawMessage) (ListPage, error)

DecodeListResult decodes a skills/list result. Only an unusable envelope is an error; per-entry failures are reported in the page.

type TruncatedError

type TruncatedError struct {
	Bound string
	Limit int64
}

TruncatedError reports that a listing stopped at a bound. It travels next to the partial result so the caller can record the listing as truncated rather than complete.

func (*TruncatedError) Error

func (e *TruncatedError) Error() string

type UnusableError

type UnusableError struct {
	Code   string
	Detail string
}

UnusableError says why a skill cannot be used: a machine Code from the Reason constants and a human Detail.

func VerifyFile

func VerifyFile(ref FileRef, content []byte) *UnusableError

VerifyFile checks the bytes against the listing: size first, then sha256. Only sha256:<64 lower-case hex> digests are understood.

func (*UnusableError) Error

func (e *UnusableError) Error() string

Directories

Path Synopsis
Package index is a memory-only full-text index of skills (spec 125, D12).
Package index is a memory-only full-text index of skills (spec 125, D12).
Package skillstest is a fake upstream MCP server that serves skills over raw JSON-RPC on HTTP.
Package skillstest is a fake upstream MCP server that serves skills over raw JSON-RPC on HTTP.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL