// 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 }