Files
archie/internal/skill/skill.go
T
sam 42a4e2465d feat(kitrun): mount the operator's skills store for agent-skills@1
A Kit's agent-skills@1 path now gets the shared skills store
(skills_dir/.agents/skills) bind-mounted read-only, whatever mode the Kit
asks for; with no skills_dir the host withholds the mount. skills_dir is
read live on every launch. skill.StoreDir exposes the store path so the
launcher does not copy the package's directory constant.

Part of archie-core-egkf.6.
2026-09-28 02:12:29 +10:00

209 lines
6.2 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
Root string // catalog root containing .agents/skills
}
// 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 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 {
// A file at .agents/skills (ENOTDIR) is not fatal -- treat as no skills.
// 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"
// StoreDir is where root keeps its skills: the directory a skills store
// mounted into a harness exposes.
func StoreDir(root string) string { return filepath.Join(root, skillsDir) }
// 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)
}