refactor(skills): parse frontmatter with yaml library

Replaces the homegrown parsing code.

Author: lvillani

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/hashicorp/go-retryablehttp v0.7.8
 	github.com/pelletier/go-toml/v2 v2.4.3
 	github.com/zalando/go-keyring v0.2.8
+	go.yaml.in/yaml/v4 v4.0.0-rc.6
 )
 
 require (

go.sum

@@ -98,6 +98,8 @@ github.com/yuin/goldmark-emoji v1.0.6 h1:QWfF2FYaXwL74tfGOW5izeiZepUDroDJfWubQI9
 github.com/yuin/goldmark-emoji v1.0.6/go.mod h1:ukxJDKFpdFb5x0a5HqbdlcKtebh086iJpI31LTKmWuA=
 github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
 github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
+go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
+go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f h1:W3F4c+6OLc6H2lb//N1q4WpJkhzJCK5J6kUi1NTVXfM=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f/go.mod h1:J1xhfL/vlindoeF/aINzNzt2Bket5bjo9sdOYzOsU80=
 golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=

internal/agent/agent_test.go

@@ -420,7 +420,7 @@ func newSkillReg(t *testing.T, dir, content string) *skills.Registry {
 }
 
 func TestActivateSkillNudgesModel(t *testing.T) {
-	content := "---\nname: git\n description: follow repo conventions\n---\nbody\n"
+	content := "---\nname: git\ndescription: follow repo conventions\n---\nbody\n"
 	reg := newSkillReg(t, "git", content)
 	skill, _ := reg.Get("git")
 

internal/skills/skills.go

@@ -13,6 +13,8 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+
+	"go.yaml.in/yaml/v4"
 )
 
 // Skill is a discovered skill's catalog metadata and the path to its SKILL.md.
@@ -89,9 +91,6 @@ func (r *Registry) load(md string) error {
 	if dir := filepath.Base(filepath.Dir(md)); dir != name {
 		log.Printf("skills: %s: name %q does not match directory %q", md, name, dir)
 	}
-	if strings.Contains(desc, ":") {
-		log.Printf("skills: %s: description for %q may contain an unquoted colon (subtly malformed YAML); loading anyway", md, name)
-	}
 	r.byName[name] = Skill{
 		Name:                   name,
 		Description:            desc,
@@ -139,15 +138,19 @@ func (r *Registry) catalog(keep func(Skill) bool) []Skill {
 	return out
 }
 
-// parseFrontmatter extracts the name, description and disable-model-invocation fields
-// from a SKILL.md's YAML frontmatter block. It is deliberately lenient: it only needs
-// the scalar keys and tolerates unquoted values containing colons, which strict YAML
-// would reject.
+// frontmatter is the metadata block at the start of a SKILL.md file.
+type frontmatter struct {
+	Name                   string `yaml:"name"`
+	Description            string `yaml:"description"`
+	DisableModelInvocation bool   `yaml:"disable-model-invocation"`
+}
+
+// parseFrontmatter extracts the metadata from a SKILL.md's YAML frontmatter block.
 func parseFrontmatter(content string) (name, desc string, disableMD bool, ok bool) {
-	// Must start with a standalone `---` line.
 	if content != "---" && !strings.HasPrefix(content, "---\n") {
 		return "", "", false, false
 	}
+
 	rest := content[3:]
 	nl := strings.IndexByte(rest, '\n')
 	if nl < 0 {
@@ -159,38 +162,12 @@ func parseFrontmatter(content string) (name, desc string, disableMD bool, ok boo
 	if end < 0 {
 		return "", "", false, false
 	}
-	for _, line := range strings.Split(rest[:end], "\n") {
-		line = strings.TrimSpace(line)
-		if line == "" || strings.HasPrefix(line, "#") {
-			continue
-		}
-		colon := strings.IndexByte(line, ':')
-		if colon < 0 {
-			continue
-		}
-		key := strings.TrimSpace(line[:colon])
-		val := strings.TrimSpace(line[colon+1:])
-		switch key {
-		case "name":
-			name = stripQuotes(val)
-		case "description":
-			desc = stripQuotes(val)
-		case "disable-model-invocation":
-			disableMD = parseBool(val)
-		}
-	}
-	return name, desc, disableMD, name != ""
-}
 
-// parseBool leniently parses a YAML boolean. It returns false for the default/empty
-// value, so an absent disable-model-invocation key never flips the flag.
-func parseBool(v string) bool {
-	switch strings.ToLower(strings.TrimSpace(v)) {
-	case "true", "yes", "y", "on", "1":
-		return true
-	default:
-		return false
+	var metadata frontmatter
+	if err := yaml.Unmarshal([]byte(rest[:end]), &metadata); err != nil {
+		return "", "", false, false
 	}
+	return metadata.Name, metadata.Description, metadata.DisableModelInvocation, metadata.Name != ""
 }
 
 // closingDelim returns the index of the first line exactly equal to `---`, or -1. It
@@ -208,14 +185,3 @@ func closingDelim(s string) int {
 		s = s[i+3:]
 	}
 }
-
-// stripQuotes removes a single matching surrounding quote pair, leaving a value with
-// stray or unbalanced quotes (e.g. an apostrophe) untouched.
-func stripQuotes(v string) string {
-	if len(v) >= 2 {
-		if (v[0] == '"' && v[len(v)-1] == '"') || (v[0] == '\'' && v[len(v)-1] == '\'') {
-			return v[1 : len(v)-1]
-		}
-	}
-	return v
-}

internal/skills/skills_test.go

@@ -76,13 +76,13 @@ func TestNew_ProjectOverridesUser(t *testing.T) {
 	}
 }
 
-func TestNew_LenientParsing(t *testing.T) {
+func TestNew_YAMLFrontmatter(t *testing.T) {
 	root := t.TempDir()
 
 	// Name/directory mismatch warns but still loads.
 	writeSkill(t, root, "mismatch-dir", "---\nname: actual-name\ndescription: a skill\n---\nbody\n")
-	// Unquoted colon in the value must not break parsing.
-	writeSkill(t, root, "pdf", "---\nname: pdf\ndescription: use when: the user shares a PDF\n---\nbody\n")
+	// YAML supports quoted values containing colons.
+	writeSkill(t, root, "pdf", "---\nname: pdf\ndescription: \"use when: the user shares a PDF\"\n---\nbody\n")
 	// A horizontal rule (`---`) in the body must not truncate the frontmatter.
 	writeSkill(t, root, "body-hr", "---\nname: body-hr\ndescription: has a rule below\n---\n\n---\n\nmarkdown body\n")
 	// A lone apostrophe must not be mangled; a matching quote pair is stripped.
@@ -115,7 +115,7 @@ func TestNew_LenientParsing(t *testing.T) {
 		t.Error("mismatched name/dir skill was not loaded (should warn and load)")
 	}
 	if s, ok := got["pdf"]; !ok || s.Description != "use when: the user shares a PDF" {
-		t.Errorf("lenient colon description not preserved: %+v", got["pdf"])
+		t.Errorf("quoted colon description not preserved: %+v", got["pdf"])
 	}
 	if s, ok := got["body-hr"]; !ok || !strings.Contains(s.Description, "rule below") {
 		t.Errorf("body horizontal rule truncated the frontmatter: %+v", got["body-hr"])
@@ -173,7 +173,7 @@ func TestModelCatalogExcludesDisabledSkills(t *testing.T) {
 	}
 }
 
-func TestParseDisabledModelInvocationVariants(t *testing.T) {
+func TestParseDisabledModelInvocation(t *testing.T) {
 	cases := []struct {
 		val  string
 		want bool
@@ -182,15 +182,13 @@ func TestParseDisabledModelInvocationVariants(t *testing.T) {
 		{val: "True", want: true},
 		{val: "yes", want: true},
 		{val: "on", want: true},
-		{val: "1", want: true},
 		{val: "false", want: false},
 		{val: "", want: false},
-		{val: "banana", want: false},
 	}
 	for _, c := range cases {
-		_, _, got, _ := parseFrontmatter("---\nname: x\ndescription: d\ndisable-model-invocation: " + c.val + "\n---\n")
-		if got != c.want {
-			t.Errorf("parseFrontmatter(disable-model-invocation: %q) = %v, want %v", c.val, got, c.want)
+		_, _, got, ok := parseFrontmatter("---\nname: x\ndescription: d\ndisable-model-invocation: " + c.val + "\n---\n")
+		if !ok || got != c.want {
+			t.Errorf("parseFrontmatter(disable-model-invocation: %q) = %v, %v; want %v, true", c.val, got, ok, c.want)
 		}
 	}
 }