Files
archie/internal/skill/skill.go
T
sam 2182cc00a5 refactor: replace hardcoded workflow→skill maps with catalog-driven lookup
Skills now declare their workflow in metadata.archie.workflow.
Catalog() scans frontmatter only (lazy, Tier 1). SkillForWorkflow()
derives the skill directory from the catalog — no hardcoded maps.

Removed workflowToSkill map (agent.go) and workflowToSkillDir switch
(worker.go). Both daemon and agent use the same catalog-based lookup.

Skills renamed to archie-wf-* convention. SKILL.md files updated with
workflow metadata field.

Progressive disclosure Tier 1: Catalog() returns name+description
+workflow. Tier 2: LoadBody() loads full body on activation.
2026-07-22 03:44:42 +10:00

194 lines
5.5 KiB
Go

// Package skill parses agentskills.io SKILL.md files and discovers skills
// from the .agents/skills/ directory convention. 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"`
Plugins []string `yaml:"plugins,omitempty"`
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
}
// Catalog scans dir/.agents/skills/*/SKILL.md and returns catalog entries
// (Tier 1: name + description + workflow only). Only the frontmatter is
// parsed — full bodies are not loaded. Missing directory returns nil.
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 {
return nil, fmt.Errorf("read skills dir %s: %w", skillsPath, err)
}
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,
})
}
return out, nil
}
// 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
}
// Skill is a parsed SKILL.md file with its frontmatter, body, and any
// bundled Yaegi plugins found in the skill's plugins/ directory.
type Skill struct {
Frontmatter Frontmatter
Body string
Dir string // skill directory name (e.g. "tdd-bugfix")
Plugins []Plugin // bundled Yaegi plugins from plugins/*.go
}
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
}
// Discover scans dir/.agents/skills/*/SKILL.md and returns a map of skill
// directory name to parsed Skill. Missing directory returns an empty map.
func Discover(dir string) (map[string]Skill, error) {
skillsPath := filepath.Join(dir, skillsDir)
entries, err := os.ReadDir(skillsPath)
if os.IsNotExist(err) {
return nil, nil
}
if err != nil {
return nil, fmt.Errorf("read skills dir %s: %w", skillsPath, err)
}
names := make([]string, 0, len(entries))
for _, e := range entries {
if e.IsDir() {
names = append(names, e.Name())
}
}
sort.Strings(names)
out := make(map[string]Skill, len(names))
for _, name := range names {
skillPath := filepath.Join(skillsPath, name, "SKILL.md")
data, err := os.ReadFile(skillPath)
if err != nil {
if os.IsNotExist(err) {
continue // directory exists but no SKILL.md
}
return nil, fmt.Errorf("read %s: %w", skillPath, err)
}
fm, body, err := Parse(data)
if err != nil {
return nil, fmt.Errorf("parse %s: %w", skillPath, err)
}
plugins, err := DiscoverPlugins(dir, name)
if err != nil {
return nil, fmt.Errorf("plugins %s: %w", name, err)
}
out[name] = Skill{Frontmatter: *fm, Body: body, Dir: name, Plugins: plugins}
}
return out, 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)
}