Files
skillshare/internal/skillpkg/skillpkg.go
T
Willie cc7d802411 feat(mcp): serve skills over MCP with the SEP-2640 Skills extension
Agents on a disposable VM, in a hosted assistant or behind an MCP gateway can
reach an MCP endpoint but not the folder skills sync to, so they got tools and
none of the user's skills (#428).

`skillshare mcp serve` is a read-only server for the skills skillshare already
manages. It declares io.modelcontextprotocol/skills and implements skills/list,
skills/get and resources/read: one entry per skill, its URI from the source
path, the full frontmatter, and every file with a sha256 digest and size.
--target applies that target's selection, and the source is reread at most
every 5 seconds so install, update, enable and disable show up without a
restart; unchanged files keep their digest. stdio is the default; --http
serves Streamable HTTP and needs SKILLSHARE_MCP_TOKEN off loopback.

Skills the extension cannot carry are skipped with a warning instead of being
published incomplete: a name that breaks the Agent Skills rules or differs from
its directory, more than 512 files or 16 MiB, or a nested skill that is not
served. --check lists them without serving. The naming rules moved to
internal/skillpkg so sync and the server share them.

Few clients support the extension yet, so the server also offers list_skills
and read_skill tools. A client that declares the extension does not see them,
so it never gets each skill twice.

sync.SelectTargetSkills is the one place that turns discovered skills into a
target's selection (enabled, include/exclude, frontmatter targets).

Refs: #428
2026-10-06 14:18:16 +08:00

119 lines
3.3 KiB
Go

// Package skillpkg reads one skill directory as an Agent Skills package: its
// full frontmatter and every regular file, within the SEP-2640 limits. It has
// no configuration dependencies, so sync can share its naming rules.
package skillpkg
import (
"fmt"
"os"
"path/filepath"
"strings"
"time"
"skillshare/internal/sourcewalk"
"skillshare/internal/utils"
)
// Per-skill limits from SEP-2640.
const (
MaxFiles = 512
MaxBytes = 16 << 20
)
// File is one regular file of a package.
type File struct {
Path string // absolute
Rel string // slash-separated, relative to the package directory
Size int64
ModTime time.Time
}
// Package is a valid skill directory.
type Package struct {
Dir string // resolved
Frontmatter map[string]any
Files []File
}
// Load reads the skill in dir. The error says why the directory is not a
// valid package. .git directories are left out; links are neither listed nor read.
func Load(dir string) (*Package, error) {
dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's
dir = utils.ResolveSymlink(dir)
content, err := os.ReadFile(filepath.Join(dir, "SKILL.md"))
if err != nil {
return nil, err
}
fm, err := utils.ParseFrontmatterMap(content)
if err != nil {
return nil, fmt.Errorf("SKILL.md has %w", err)
}
name, _ := fm["name"].(string)
if reason := ValidateName(name, dirName); reason != "" {
return nil, fmt.Errorf("%s", reason)
}
if desc, _ := fm["description"].(string); strings.TrimSpace(desc) == "" {
return nil, fmt.Errorf("SKILL.md is missing a description")
}
p := &Package{Dir: dir, Frontmatter: fm}
var total int64
err = sourcewalk.Walk(dir, sourcewalk.Options{}, func(path string, info os.FileInfo, err error) error {
if err != nil {
return err
}
if info.IsDir() {
if info.Name() == ".git" {
return filepath.SkipDir
}
return nil
}
if !info.Mode().IsRegular() {
return nil
}
if len(p.Files) == MaxFiles {
return fmt.Errorf("has more than %d files", MaxFiles)
}
if total += info.Size(); total > MaxBytes {
return fmt.Errorf("is larger than 16 MiB")
}
rel, err := filepath.Rel(dir, path)
if err != nil {
return err
}
p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Size: info.Size(), ModTime: info.ModTime()})
return nil
})
if err != nil {
return nil, err
}
return p, nil
}
// ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules
// (including name == directory name), or "" when it follows them.
func ValidateName(name, dirName string) string {
if name == "" {
return "SKILL.md is missing a name"
}
if len(name) > 64 {
return fmt.Sprintf("SKILL.md name %q is longer than 64 characters", name)
}
if strings.HasPrefix(name, "-") || strings.HasSuffix(name, "-") {
return fmt.Sprintf("SKILL.md name %q cannot start or end with '-'", name)
}
if strings.Contains(name, "--") {
return fmt.Sprintf("SKILL.md name %q cannot contain consecutive hyphens", name)
}
for _, r := range name {
if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' {
continue
}
return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", name)
}
if name != dirName {
return fmt.Sprintf("SKILL.md name %q does not match directory name %q", name, dirName)
}
return ""
}