bd4f1437bc
Adds a SKILL.md bundle validator, immutable per-skill versions with content digests and deduplication, protocol requests to import, list and show skills, and the pipelines skills import/list/show commands. Imports are serialised so concurrent imports never share a version number.
174 lines
4.3 KiB
Go
174 lines
4.3 KiB
Go
// Package skills validates and fingerprints Claude/Codex/OpenCode/Pi skill bundles.
|
|
package skills
|
|
|
|
import (
|
|
"crypto/sha256"
|
|
"encoding/hex"
|
|
"fmt"
|
|
"io/fs"
|
|
"os"
|
|
"path/filepath"
|
|
"regexp"
|
|
"sort"
|
|
"strings"
|
|
)
|
|
|
|
const (
|
|
MaxFiles = 200
|
|
MaxTotalBytes = 5 * 1024 * 1024
|
|
MaxFileBytes = 1024 * 1024
|
|
)
|
|
|
|
var slug = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
|
|
|
|
// ValidateName checks the server-facing skill name before it is used in a
|
|
// filesystem path.
|
|
func ValidateName(name string) error {
|
|
if !slug.MatchString(name) {
|
|
return fmt.Errorf("skill name must be a lowercase slug")
|
|
}
|
|
return nil
|
|
}
|
|
|
|
type File struct {
|
|
Path string
|
|
Bytes []byte
|
|
}
|
|
type Bundle struct {
|
|
Name, Description, Digest string
|
|
Files []File
|
|
TotalBytes int64
|
|
}
|
|
|
|
func Validate(root string) (Bundle, error) {
|
|
root, err := filepath.Abs(root)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
st, err := os.Lstat(root)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
if st.Mode()&os.ModeSymlink != 0 {
|
|
return Bundle{}, fmt.Errorf("symlinks are not allowed: %s", root)
|
|
}
|
|
if !st.IsDir() {
|
|
return Bundle{}, fmt.Errorf("skill path is not a directory")
|
|
}
|
|
var files []File
|
|
err = filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
|
|
if walkErr != nil {
|
|
return walkErr
|
|
}
|
|
rel, e := filepath.Rel(root, path)
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if rel == "." {
|
|
return nil
|
|
}
|
|
if d.Type()&os.ModeSymlink != 0 {
|
|
return fmt.Errorf("symlinks are not allowed: %s", rel)
|
|
}
|
|
if d.IsDir() {
|
|
if filepath.Dir(rel) == "." && rel != "references" && rel != "scripts" && rel != "assets" {
|
|
return fmt.Errorf("unsupported top-level directory: %s", rel)
|
|
}
|
|
return nil
|
|
}
|
|
clean := filepath.ToSlash(rel)
|
|
if filepath.Dir(rel) == "." && clean != "SKILL.md" {
|
|
return fmt.Errorf("unsupported top-level file: %s", clean)
|
|
}
|
|
if filepath.IsAbs(rel) || strings.HasPrefix(clean, "../") || clean == ".." {
|
|
return fmt.Errorf("invalid path: %s", rel)
|
|
}
|
|
if filepath.Base(rel) == "SKILL.md" && filepath.Dir(rel) != "." {
|
|
return fmt.Errorf("nested SKILL.md is not allowed: %s", rel)
|
|
}
|
|
if len(files) >= MaxFiles {
|
|
return fmt.Errorf("skill has more than %d files", MaxFiles)
|
|
}
|
|
info, e := d.Info()
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if info.Size() > MaxFileBytes {
|
|
return fmt.Errorf("file %s exceeds %d bytes", clean, MaxFileBytes)
|
|
}
|
|
b, e := os.ReadFile(path)
|
|
if e != nil {
|
|
return e
|
|
}
|
|
if info.Mode()&0111 != 0 && !strings.HasPrefix(clean, "scripts/") {
|
|
return fmt.Errorf("executable outside scripts/: %s", clean)
|
|
}
|
|
files = append(files, File{Path: clean, Bytes: b})
|
|
return nil
|
|
})
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
sort.Slice(files, func(i, j int) bool { return files[i].Path < files[j].Path })
|
|
var md []byte
|
|
for _, f := range files {
|
|
if f.Path == "SKILL.md" {
|
|
md = f.Bytes
|
|
break
|
|
}
|
|
}
|
|
if md == nil {
|
|
return Bundle{}, fmt.Errorf("skill must contain exactly one top-level SKILL.md")
|
|
}
|
|
name, desc, err := frontmatter(md)
|
|
if err != nil {
|
|
return Bundle{}, err
|
|
}
|
|
if err := ValidateName(name); err != nil {
|
|
return Bundle{}, fmt.Errorf("frontmatter name must be a lowercase slug")
|
|
}
|
|
var total int64
|
|
h := sha256.New()
|
|
for _, f := range files {
|
|
total += int64(len(f.Bytes))
|
|
fmt.Fprintf(h, "%s\x00%d\x00", f.Path, len(f.Bytes))
|
|
h.Write(f.Bytes)
|
|
}
|
|
if total > MaxTotalBytes {
|
|
return Bundle{}, fmt.Errorf("skill exceeds %d total bytes", MaxTotalBytes)
|
|
}
|
|
return Bundle{Name: name, Description: desc, Digest: hex.EncodeToString(h.Sum(nil)), Files: files, TotalBytes: total}, nil
|
|
}
|
|
|
|
func frontmatter(b []byte) (string, string, error) {
|
|
s := strings.ReplaceAll(string(b), "\r\n", "\n")
|
|
lines := strings.Split(s, "\n")
|
|
if len(lines) < 3 || strings.TrimSpace(lines[0]) != "---" {
|
|
return "", "", fmt.Errorf("SKILL.md must begin with YAML frontmatter")
|
|
}
|
|
name, desc := "", ""
|
|
end := -1
|
|
for i := 1; i < len(lines); i++ {
|
|
if strings.TrimSpace(lines[i]) == "---" {
|
|
end = i
|
|
break
|
|
}
|
|
k, v, ok := strings.Cut(lines[i], ":")
|
|
if !ok {
|
|
continue
|
|
}
|
|
v = strings.TrimSpace(v)
|
|
v = strings.Trim(v, "\"'")
|
|
switch strings.TrimSpace(k) {
|
|
case "name":
|
|
name = v
|
|
case "description":
|
|
desc = v
|
|
}
|
|
}
|
|
if end < 0 || name == "" || desc == "" {
|
|
return "", "", fmt.Errorf("SKILL.md frontmatter requires name and description")
|
|
}
|
|
return name, desc, nil
|
|
}
|