Skip to content

mission control for agent skills

fix(scan): handle nested skill symlinks

Alvin Unreal084c4491da65
diff --git a/internal/scan/scan.go b/internal/scan/scan.go
index 4d8bfba..5224cb8 100644
--- a/internal/scan/scan.go
+++ b/internal/scan/scan.go
@@ -423,52 +423,101 @@ func scanLocationRecords(loc agents.Location) []scannedLocationRecord {
// scanNestedSkills appends records for SKILL.md files under loc.Root that are
// not immediate children (depth > 1). Immediate children are already handled by
// the one-level loop in scanLocationRecords; this only adds deeper finds so
-// they are not double-counted. The root is symlink-resolved before walking.
-// An immediate-child directory that contains nested SKILL.md files is a bundle
-// (not a skill itself); its record is dropped from the returned slice.
+// they are not double-counted. The root is symlink-resolved before walking, but
+// records retain paths rooted at loc.Root. An immediate-child directory that
+// contains nested SKILL.md files is a bundle (not a skill itself); its record is
+// dropped from the returned slice.
func scanNestedSkills(loc agents.Location, records []scannedLocationRecord) []scannedLocationRecord {
root, err := filepath.EvalSymlinks(loc.Root)
if err != nil {
return records
}
- // Track skill dirs already recorded by the one-level scan to avoid dups.
- seen := make(map[string]bool, len(records))
- for _, r := range records {
- if r.skillPath != "" {
- seen[filepath.Clean(filepath.Dir(r.skillPath))] = true
- }
- }
// bundleDirs collects immediate-child directories of loc.Root that contain
- // nested SKILL.md files. Keyed by loc.Root-joined path so it matches the
- // one-level records' observed.Path (which uses loc.Root, not the resolved
- // root).
+ // nested SKILL.md files. Keyed by logical paths so it matches the one-level
+ // records' observed.Path.
bundleDirs := map[string]bool{}
_ = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
if err != nil {
return nil
}
+ rel, relErr := filepath.Rel(root, path)
+ if relErr != nil {
+ return nil
+ }
+ parts := strings.Split(filepath.ToSlash(rel), "/")
+ logicalPath := filepath.Join(loc.Root, filepath.FromSlash(rel))
+
+ // WalkDir does not follow symlinks. A symlinked directory can still be a
+ // nested skill, but it must not become a traversal entry point. Symlinked
+ // files fall through to ordinary SKILL.md handling below.
+ if d.Type()&os.ModeSymlink != 0 {
+ st, statErr := os.Stat(path)
+ if statErr == nil && st.IsDir() {
+ name := d.Name()
+ if len(parts) <= 1 || name == ".git" || name == "node_modules" || name == "vendor" || name == ".agents" || name == ".slim" || strings.HasPrefix(name, ".") || len(parts) > 5 {
+ return nil
+ }
+ skillFile := filepath.Join(path, "SKILL.md")
+ logicalSkillFile := filepath.Join(logicalPath, "SKILL.md")
+ if _, skillErr := os.Stat(skillFile); errors.Is(skillErr, os.ErrNotExist) {
+ return nil
+ }
+ bundleDirs[filepath.Clean(filepath.Join(loc.Root, parts[0]))] = true
+ target, _ := os.Readlink(path)
+ if !filepath.IsAbs(target) {
+ target = filepath.Join(filepath.Dir(logicalPath), target)
+ }
+ observed := model.ObservedPath{
+ Path: logicalPath,
+ Scope: loc.Scope,
+ Agent: loc.AgentName,
+ Status: model.StatusSymlink,
+ TargetPath: filepath.Clean(target),
+ }
+ doc, parseErr := frontmatter.ParseFile(skillFile)
+ if parseErr != nil {
+ issueType := "invalid_frontmatter"
+ if errors.Is(parseErr, os.ErrNotExist) {
+ issueType = "missing_skill_md"
+ }
+ records = append(records, scannedLocationRecord{
+ keyHint: filepath.Base(logicalPath),
+ name: filepath.Base(logicalPath),
+ observed: observed,
+ healthIssues: []model.HealthIssue{{Type: issueType, Severity: "error", Message: fmt.Sprintf("invalid SKILL.md: %v", parseErr), Path: logicalSkillFile}},
+ })
+ return nil
+ }
+ canonicalPath := ""
+ if loc.Canonical {
+ canonicalPath = logicalPath
+ }
+ records = append(records, scannedLocationRecord{
+ keyHint: filepath.Base(logicalPath),
+ name: doc.Name,
+ description: doc.Description,
+ skillPath: logicalSkillFile,
+ preview: doc.Raw,
+ canonicalPath: canonicalPath,
+ observed: observed,
+ })
+ return nil
+ }
+ }
if d.IsDir() {
name := d.Name()
if name == ".git" || name == "node_modules" || name == "vendor" || name == ".agents" || name == ".slim" || strings.HasPrefix(name, ".") {
return filepath.SkipDir
}
- rel, relErr := filepath.Rel(root, path)
- if relErr == nil {
- depth := len(strings.Split(filepath.ToSlash(rel), "/"))
- if depth > 5 {
- return filepath.SkipDir
- }
+ depth := len(parts)
+ if depth > 5 {
+ return filepath.SkipDir
}
return nil
}
if d.Name() != "SKILL.md" {
return nil
}
- rel, relErr := filepath.Rel(root, path)
- if relErr != nil {
- return nil
- }
- parts := strings.Split(filepath.ToSlash(rel), "/")
// A SKILL.md is "nested" (not an immediate child) only when its skill
// directory sits below root's first level. The file's component count is
// one more than its dir depth (the trailing "SKILL.md"), so a skill dir
@@ -480,29 +529,38 @@ func scanNestedSkills(loc agents.Location, records []scannedLocationRecord) []sc
// This nested SKILL.md lives under an immediate-child directory of
// loc.Root; that child is a bundle, not a skill.
bundleDirs[filepath.Clean(filepath.Join(loc.Root, parts[0]))] = true
- skillDir := filepath.Dir(path)
- if seen[filepath.Clean(skillDir)] {
- return nil
+ logicalSkillDir := filepath.Dir(logicalPath)
+ status := model.StatusCopy
+ if loc.Canonical {
+ status = model.StatusCanonical
}
doc, perr := frontmatter.ParseFile(path)
if perr != nil {
+ issueType := "invalid_frontmatter"
+ if errors.Is(perr, os.ErrNotExist) {
+ issueType = "missing_skill_md"
+ }
+ records = append(records, scannedLocationRecord{
+ keyHint: filepath.Base(logicalSkillDir),
+ name: filepath.Base(logicalSkillDir),
+ observed: model.ObservedPath{Path: logicalSkillDir, Scope: loc.Scope, Agent: loc.AgentName, Status: status},
+ healthIssues: []model.HealthIssue{{Type: issueType, Severity: "error", Message: fmt.Sprintf("invalid SKILL.md: %v", perr), Path: logicalPath}},
+ })
return nil
}
- status := model.StatusCopy
canonicalPath := ""
if loc.Canonical {
- status = model.StatusCanonical
- canonicalPath = skillDir
+ canonicalPath = logicalSkillDir
}
records = append(records, scannedLocationRecord{
- keyHint: filepath.Base(skillDir),
+ keyHint: filepath.Base(logicalSkillDir),
name: doc.Name,
description: doc.Description,
- skillPath: path,
+ skillPath: logicalPath,
preview: doc.Raw,
canonicalPath: canonicalPath,
observed: model.ObservedPath{
- Path: skillDir,
+ Path: logicalSkillDir,
Scope: loc.Scope,
Agent: loc.AgentName,
Status: status,
diff --git a/internal/scan/scan_test.go b/internal/scan/scan_test.go
index 572253b..7de9359 100644
--- a/internal/scan/scan_test.go
+++ b/internal/scan/scan_test.go
@@ -4,8 +4,10 @@ import (
"encoding/json"
"os"
"path/filepath"
+ "strings"
"testing"
+ "github.com/alvinunreal/lazyskills/internal/agents"
"github.com/alvinunreal/lazyskills/internal/model"
)
@@ -623,3 +625,159 @@ func TestScanDisabledRelativeSymlinkDoesNotReportBroken(t *testing.T) {
t.Fatal("expected disabled symlink target preview to be parsed")
}
}
+
+func TestNestedSkillsUnderSymlinkedRootKeepLogicalPaths(t *testing.T) {
+ withHome(t)
+ cwd := t.TempDir()
+ target := filepath.Join(t.TempDir(), "skills")
+ writeSkill(t, filepath.Join(target, "direct"), "Direct", "immediate")
+ writeSkill(t, filepath.Join(target, "bundle", "one"), "One", "first")
+ writeSkill(t, filepath.Join(target, "bundle", "two"), "Two", "second")
+ root := filepath.Join(cwd, ".agents", "skills")
+ if err := os.MkdirAll(filepath.Dir(root), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Symlink(target, root); err != nil {
+ t.Fatal(err)
+ }
+
+ records := scanLocationRecords(agents.Location{
+ Root: root,
+ Scope: model.ScopeProject,
+ AgentName: "universal",
+ Canonical: true,
+ })
+ if len(records) != 3 {
+ t.Fatalf("expected immediate and nested skills, got %#v", records)
+ }
+ expectedPaths := map[string]string{
+ "Direct": filepath.Join(root, "direct"),
+ "One": filepath.Join(root, "bundle", "one"),
+ "Two": filepath.Join(root, "bundle", "two"),
+ }
+ seen := map[string]bool{}
+ for _, record := range records {
+ expectedPath, ok := expectedPaths[record.name]
+ if !ok {
+ t.Fatalf("unexpected skill record: %#v", record)
+ }
+ if seen[record.name] {
+ t.Fatalf("expected %s exactly once, got %#v", record.name, records)
+ }
+ seen[record.name] = true
+ if record.observed.Path != expectedPath {
+ t.Fatalf("expected logical observed path %q, got %#v", expectedPath, record.observed)
+ }
+ if strings.Contains(record.skillPath, target) || strings.Contains(record.canonicalPath, target) {
+ t.Fatalf("resolved target leaked into skill paths: %#v", record)
+ }
+ if strings.Contains(record.observed.Path, target) {
+ t.Fatalf("resolved target leaked into observed path: %#v", record.observed)
+ }
+ }
+ if len(seen) != len(expectedPaths) {
+ t.Fatalf("expected all logical skills exactly once, got %#v", records)
+ }
+}
+
+func TestNestedSymlinkedSkillIsRecordedWithoutTraversal(t *testing.T) {
+ withHome(t)
+ cwd := t.TempDir()
+ target := filepath.Join(t.TempDir(), "linked-skill")
+ writeSkill(t, target, "Linked", "linked skill")
+ root := filepath.Join(cwd, ".agents", "skills")
+ link := filepath.Join(root, "bundle", "linked")
+ if err := os.MkdirAll(filepath.Dir(link), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Symlink(target, link); err != nil {
+ t.Fatal(err)
+ }
+
+ res, err := Run(cwd)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(res.Skills) != 1 || res.Skills[0].Name != "Linked" {
+ t.Fatalf("expected only linked nested skill, got %#v", res.Skills)
+ }
+ sk := res.Skills[0]
+ if sk.SkillPath != filepath.Join(link, "SKILL.md") || sk.CanonicalPath != link {
+ t.Fatalf("expected logical canonical paths, got %#v", sk)
+ }
+ if hasIssue(sk.HealthIssues, "ghost_agent_skill") {
+ t.Fatalf("canonical nested symlink should not be a ghost skill: %#v", sk.HealthIssues)
+ }
+ for _, observed := range sk.ObservedPaths {
+ if observed.Path != link || observed.Status != model.StatusSymlink || observed.TargetPath != target {
+ t.Fatalf("unexpected nested symlink observation: %#v", observed)
+ }
+ }
+}
+
+func TestNestedSymlinkedSkillFileIsDiscoveredNormally(t *testing.T) {
+ withHome(t)
+ cwd := t.TempDir()
+ source := filepath.Join(t.TempDir(), "source")
+ writeSkill(t, source, "Linked File", "linked file skill")
+ child := filepath.Join(cwd, ".agents", "skills", "bundle", "child")
+ if err := os.MkdirAll(child, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.Symlink(filepath.Join(source, "SKILL.md"), filepath.Join(child, "SKILL.md")); err != nil {
+ t.Fatal(err)
+ }
+
+ res, err := Run(cwd)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(res.Skills) != 1 || res.Skills[0].Name != "Linked File" {
+ t.Fatalf("expected symlinked SKILL.md to be discovered, got %#v", res.Skills)
+ }
+ if res.Skills[0].ObservedPaths[0].Status != model.StatusCanonical {
+ t.Fatalf("symlinked SKILL.md should use ordinary canonical handling: %#v", res.Skills[0].ObservedPaths)
+ }
+}
+
+func TestMalformedNestedSkillReportsDiagnosticAndSuppressesBundle(t *testing.T) {
+ withHome(t)
+ cwd := t.TempDir()
+ root := filepath.Join(cwd, ".agents", "skills")
+ bundle := filepath.Join(root, "bundle")
+ writeSkill(t, bundle, "Bundle", "container")
+ bad := filepath.Join(bundle, "bad")
+ if err := os.MkdirAll(bad, 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(filepath.Join(bad, "SKILL.md"), []byte("---\nname: 123\n---\n"), 0o644); err != nil {
+ t.Fatal(err)
+ }
+
+ res, err := Run(cwd)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(res.Skills) != 1 || res.Skills[0].Name != "bad" {
+ t.Fatalf("expected malformed nested skill and no bundle record, got %#v", res.Skills)
+ }
+ if !hasIssue(res.Skills[0].HealthIssues, "invalid_frontmatter") {
+ t.Fatalf("expected invalid_frontmatter issue, got %#v", res.Skills[0].HealthIssues)
+ }
+}
+
+func TestNestedBundleDiscoversChildrenAndSuppressesContainer(t *testing.T) {
+ withHome(t)
+ cwd := t.TempDir()
+ bundle := filepath.Join(cwd, ".agents", "skills", "bundle")
+ writeSkill(t, bundle, "Bundle", "container")
+ writeSkill(t, filepath.Join(bundle, "child"), "Child", "nested skill")
+
+ res, err := Run(cwd)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(res.Skills) != 1 || res.Skills[0].Name != "Child" {
+ t.Fatalf("expected only nested child skill, got %#v", res.Skills)
+ }
+}