Merge pull request #1139 from rumpl/skills-spec

Adhere to the skills spec

Author: dgageot

golang_developer.yaml

@@ -94,6 +94,7 @@ agents:
       - type: filesystem
       - type: shell
       - type: todo
+      - type: fetch
     sub_agents:
       - librarian
 

pkg/skills/skills.go

@@ -16,18 +16,32 @@ const (
 	formatCodex  skillFormat = "codex"
 
 	skillFile = "SKILL.md"
+
+	maxNameLength        = 64
+	maxDescriptionLength = 1024
+	maxCompatLength      = 500
 )
 
+var namePattern = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`)
+
 type Skill struct {
-	Name        string
-	Description string
-	FilePath    string
-	BaseDir     string
+	Name          string
+	Description   string
+	FilePath      string
+	BaseDir       string
+	License       string
+	Compatibility string
+	Metadata      map[string]string
+	AllowedTools  []string
 }
 
 type frontmatter struct {
-	Name        string
-	Description string
+	Name          string
+	Description   string
+	License       string
+	Compatibility string
+	Metadata      map[string]string
+	AllowedTools  []string
 }
 
 func stripQuotes(value string) string {
@@ -40,6 +54,13 @@ func stripQuotes(value string) string {
 	return value
 }
 
+func isValidName(name string) bool {
+	if name == "" || len(name) > maxNameLength {
+		return false
+	}
+	return namePattern.MatchString(name)
+}
+
 func parseFrontmatter(content string) (frontmatter, string) {
 	fm := frontmatter{}
 
@@ -58,8 +79,25 @@ func parseFrontmatter(content string) (frontmatter, string) {
 	frontmatterBlock := normalizedContent[4 : endIndex+3]
 	body := strings.TrimSpace(normalizedContent[endIndex+7:])
 
-	lineRegex := regexp.MustCompile(`^(\w+):\s*(.*)$`)
+	lineRegex := regexp.MustCompile(`^([\w-]+):\s*(.*)$`)
+	metadataRegex := regexp.MustCompile(`^\s+(\w+):\s*(.*)$`)
+	inMetadata := false
+
 	for line := range strings.SplitSeq(frontmatterBlock, "\n") {
+		if inMetadata {
+			matches := metadataRegex.FindStringSubmatch(line)
+			if matches != nil {
+				key := matches[1]
+				value := stripQuotes(strings.TrimSpace(matches[2]))
+				if fm.Metadata == nil {
+					fm.Metadata = make(map[string]string)
+				}
+				fm.Metadata[key] = value
+				continue
+			}
+			inMetadata = false
+		}
+
 		matches := lineRegex.FindStringSubmatch(line)
 		if matches != nil {
 			key := matches[1]
@@ -69,6 +107,17 @@ func parseFrontmatter(content string) (frontmatter, string) {
 				fm.Name = value
 			case "description":
 				fm.Description = value
+			case "license":
+				fm.License = value
+			case "compatibility":
+				fm.Compatibility = value
+			case "metadata":
+				inMetadata = true
+				fm.Metadata = make(map[string]string)
+			case "allowed-tools":
+				if value != "" {
+					fm.AllowedTools = strings.Fields(value)
+				}
 			}
 		}
 	}
@@ -106,14 +155,14 @@ func loadSkillsFromDir(dir string, format skillFormat) []Skill {
 				continue
 			}
 
-			skillFile := filepath.Join(fullPath, skillFile)
-			rawContent, err := os.ReadFile(skillFile)
+			skillFilePath := filepath.Join(fullPath, skillFile)
+			rawContent, err := os.ReadFile(skillFilePath)
 			if err != nil {
 				continue
 			}
 
 			fm, _ := parseFrontmatter(string(rawContent))
-			if fm.Description == "" {
+			if !isValidFrontmatter(fm, entry.Name()) {
 				continue
 			}
 
@@ -123,10 +172,14 @@ func loadSkillsFromDir(dir string, format skillFormat) []Skill {
 			}
 
 			skills = append(skills, Skill{
-				Name:        name,
-				Description: fm.Description,
-				FilePath:    skillFile,
-				BaseDir:     fullPath,
+				Name:          name,
+				Description:   fm.Description,
+				FilePath:      skillFilePath,
+				BaseDir:       fullPath,
+				License:       fm.License,
+				Compatibility: fm.Compatibility,
+				Metadata:      fm.Metadata,
+				AllowedTools:  fm.AllowedTools,
 			})
 
 		case formatCodex:
@@ -138,22 +191,28 @@ func loadSkillsFromDir(dir string, format skillFormat) []Skill {
 					continue
 				}
 
+				skillDir := filepath.Dir(fullPath)
+				dirName := filepath.Base(skillDir)
+
 				fm, _ := parseFrontmatter(string(rawContent))
-				if fm.Description == "" {
+				if !isValidFrontmatter(fm, dirName) {
 					continue
 				}
 
-				skillDir := filepath.Dir(fullPath)
 				name := fm.Name
 				if name == "" {
-					name = filepath.Base(skillDir)
+					name = dirName
 				}
 
 				skills = append(skills, Skill{
-					Name:        name,
-					Description: fm.Description,
-					FilePath:    fullPath,
-					BaseDir:     skillDir,
+					Name:          name,
+					Description:   fm.Description,
+					FilePath:      fullPath,
+					BaseDir:       skillDir,
+					License:       fm.License,
+					Compatibility: fm.Compatibility,
+					Metadata:      fm.Metadata,
+					AllowedTools:  fm.AllowedTools,
 				})
 			}
 		}
@@ -162,6 +221,27 @@ func loadSkillsFromDir(dir string, format skillFormat) []Skill {
 	return skills
 }
 
+func isValidFrontmatter(fm frontmatter, dirName string) bool {
+	if fm.Description == "" || len(fm.Description) > maxDescriptionLength {
+		return false
+	}
+
+	if fm.Compatibility != "" && len(fm.Compatibility) > maxCompatLength {
+		return false
+	}
+
+	if fm.Name != "" {
+		if !isValidName(fm.Name) {
+			return false
+		}
+		if fm.Name != dirName {
+			return false
+		}
+	}
+
+	return true
+}
+
 func Load() []Skill {
 	skillMap := make(map[string]Skill)
 
@@ -202,21 +282,24 @@ func BuildSkillsPrompt(skills []Skill) string {
 	}
 
 	var sb strings.Builder
-	sb.WriteString("\n\n<available_skills>\n")
-	sb.WriteString("The following skills provide specialized instructions for specific tasks.\n")
-	sb.WriteString("Use the read_file tool to load a skill's file when the task matches its description.\n")
-	sb.WriteString("Skills may contain {baseDir} placeholders - replace them with the skill's base directory path.\n\n")
+	sb.WriteString("The following skills provide specialized instructions for specific tasks. ")
+	sb.WriteString("Each skill's description indicates what it does and when to use it.\n\n")
+	sb.WriteString("When a user's request matches a skill's description, use the read_file tool to load the skill's SKILL.md file from the location path. ")
+	sb.WriteString("The file contains detailed instructions to follow for that task.\n\n")
 
+	sb.WriteString("\n\n<available_skills>\n")
 	for _, skill := range skills {
-		sb.WriteString("- ")
+		sb.WriteString("  <skill>\n")
+		sb.WriteString("    <name>")
 		sb.WriteString(skill.Name)
-		sb.WriteString(": ")
+		sb.WriteString("</name>\n")
+		sb.WriteString("    <description>")
 		sb.WriteString(skill.Description)
-		sb.WriteString("\n  File: ")
+		sb.WriteString("</description>\n")
+		sb.WriteString("    <location>")
 		sb.WriteString(skill.FilePath)
-		sb.WriteString("\n  Base directory: ")
-		sb.WriteString(skill.BaseDir)
-		sb.WriteString("\n")
+		sb.WriteString("</location>\n")
+		sb.WriteString("  </skill>\n")
 	}
 
 	sb.WriteString("</available_skills>")