// Package skill parses agentskills.io SKILL.md files and discovers skills. // It follows the same discovery // pattern as internal/workflow/wfeval (missing directory is not an error). package skill import ( "fmt" "os" "path/filepath" "sort" "strings" "gopkg.in/yaml.v3" ) // Frontmatter is the parsed YAML frontmatter of a SKILL.md file. type Frontmatter struct { Name string `yaml:"name"` Description string `yaml:"description"` Version string `yaml:"version"` Metadata struct { Archie *struct { Tools []string `yaml:"tools"` Engine string `yaml:"engine"` Workflow string `yaml:"workflow,omitempty"` } `yaml:"archie"` } `yaml:"metadata"` } // CatalogEntry is a lightweight skill reference -- name + description // only (~100 tokens). Loaded at daemon startup for skill discovery. // The full body is loaded on activation via LoadBody. agentskills.io // progressive disclosure Tier 1. type CatalogEntry struct { Name string Description string Workflow string // from metadata.archie.workflow -- which workflow this skill handles Dir string // skill directory name Root string // catalog root containing.agents/skills // Body is the skill's instructions when they are held in memory rather // than in Dir under Root. Body string } // EntryFromContent builds a catalog entry for a SKILL.md held in memory. func EntryFromContent(content []byte) (CatalogEntry, error) { fm, body, err := Parse(content) if err != nil { return CatalogEntry{}, err } if fm.Name == "" { return CatalogEntry{}, fmt.Errorf("SKILL.md has no name") } entry := CatalogEntry{Name: fm.Name, Description: fm.Description, Body: body} if fm.Metadata.Archie != nil { entry.Workflow = fm.Metadata.Archie.Workflow } return entry, nil } // Only the frontmatter is parsed -- full bodies are not loaded. Missing // directory or a file at the skills path returns nil (no error) -- the caller // treats this as "no skills." func Catalog(dir string) ([]CatalogEntry, error) { skillsPath := filepath.Join(dir, skillsDir) entries, err := os.ReadDir(skillsPath) if os.IsNotExist(err) { return nil, nil } if err != nil { // Same for permission errors and other non-fatal ReadDir failures. return nil, nil //nolint:nilerr // documented above: a non-directory or unreadable skills path means no skills, not a fatal error } var names []string for _, e := range entries { if e.IsDir() { names = append(names, e.Name()) } } sort.Strings(names) var out []CatalogEntry for _, name := range names { skillPath := filepath.Join(skillsPath, name, "SKILL.md") data, err := os.ReadFile(skillPath) if err != nil { continue } fm, _, err := Parse(data) if err != nil || fm == nil { continue } wf := "" if fm.Metadata.Archie != nil { wf = fm.Metadata.Archie.Workflow } out = append(out, CatalogEntry{ Name: fm.Name, Description: fm.Description, Workflow: wf, Dir: name, Root: dir, }) } return out, nil } // CatalogRoots merges catalogues from roots in precedence order. The first // root containing a skill name wins, so callers can layer project skills over // shared and user-global skills deterministically. func CatalogRoots(roots ...string) ([]CatalogEntry, error) { seen := make(map[string]struct{}) var out []CatalogEntry for _, root := range roots { entries, err := Catalog(root) if err != nil { return nil, err } for _, entry := range entries { if _, ok := seen[entry.Name]; ok { continue } seen[entry.Name] = struct{}{} out = append(out, entry) } } sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) return out, nil } // DefaultRoots returns the discovery roots for a daemon. Explicit project and // shared roots take precedence over the user's global skills directory. func DefaultRoots(workDir, sharedDir string) []string { var roots []string for _, root := range []string{workDir, sharedDir} { if root != "" && !containsRoot(roots, root) { roots = append(roots, root) } } if home, err := os.UserHomeDir(); err == nil && home != "" && !containsRoot(roots, home) { roots = append(roots, home) } return roots } // containsRoot compares roots after normalising trailing separators, so // "/srv/skills" and "/srv/skills/" are one root rather than two -- otherwise // the same directory is scanned twice and every skill in it appears twice. func containsRoot(roots []string, root string) bool { target := normaliseRoot(root) for _, existing := range roots { if normaliseRoot(existing) == target { return true } } return false } func normaliseRoot(root string) string { if root == "" { return root } return filepath.Clean(root) } // SkillForWorkflow returns the catalog entry whose Workflow field matches // the given workflow name, or nil if no skill declares that workflow. // Replaces hardcoded workflow→skill lookup tables. func SkillForWorkflow(catalog []CatalogEntry, workflow string) *CatalogEntry { for i := range catalog { if catalog[i].Workflow == workflow { return &catalog[i] } } return nil } const skillsDir = ".agents/skills" // Parse extracts YAML frontmatter and body from SKILL.md content. // The frontmatter is delimited by "---" lines. If no frontmatter is found, // the entire content is returned as the body with a zero Frontmatter. func Parse(src []byte) (*Frontmatter, string, error) { text := string(src) if !strings.HasPrefix(text, "---\n") { return &Frontmatter{}, text, nil } // Find the closing "---". end := strings.Index(text[4:], "\n---\n") if end == -1 { // Malformed: starts with --- but no closing delimiter. return &Frontmatter{}, text, nil } end += 4 // adjust for the initial 4-byte skip var fm Frontmatter if err := yaml.Unmarshal([]byte(text[4:end]), &fm); err != nil { return nil, "", fmt.Errorf("yaml frontmatter: %w", err) } body := strings.TrimSpace(text[end+5:]) // skip "\n---\n" return &fm, body, nil } // LoadBody loads the raw SKILL.md body for a specific skill directory name. // Returns "" if the skill directory or SKILL.md does not exist. func LoadBody(dir, skillDirName string) string { skillPath := filepath.Join(dir, skillsDir, skillDirName, "SKILL.md") data, err := os.ReadFile(skillPath) if err != nil { return "" } _, body, err := Parse(data) if err != nil { return "" } return strings.TrimSpace(body) }