discovery

Documentation

Overview

Package discovery locates SKILL.md bundles within fetched material and enforces naming and frontmatter schema rules.

Index

• Variables
• func DefaultIgnoreDirs() map[string]bool
• func NormalizeID(folder string) string
• type Diagnostic
• type DiscoveredSkill
• type DuplicateConflict
• type Options
• type Result
  • func DiscoverAll(root string, opts Options) (Result, error)
• type Severity
• type Skill
  • func Discover(root, explicitPath string) (Skill, error)

Variables

var (
	// ErrNoSkill is returned when no SKILL.md can be found.
	ErrNoSkill = errors.New("no SKILL.md found")
	// ErrAmbiguousSkill is returned when multiple skills are found and no
	// explicit path selects one.
	ErrAmbiguousSkill = errors.New("multiple SKILL.md found; specify a path")
)

Sentinel discovery errors.

Functions

func DefaultIgnoreDirs

func DefaultIgnoreDirs() map[string]bool

DefaultIgnoreDirs are the directory names pruned during a scan so noisy or unsafe trees are never descended (FR-004).

func NormalizeID

func NormalizeID(folder string) string

NormalizeID exposes the normalized-identity derivation for callers outside the package (e.g. the installer comparing a selected id to frontmatter).

Types

type Diagnostic

type Diagnostic struct {
	Severity Severity
	Message  string
	Path     string // in-repo path the diagnostic concerns (forward-slash)
}

Diagnostic is a single validation finding about a discovered skill.

type DiscoveredSkill

type DiscoveredSkill struct {
	ID          string // normalized, folder-derived identity (R2)
	DisplayName string // frontmatter name, else humanized folder name (FR-007)
	Description string
	RepoPath    string // skill dir relative to source root, forward-slash; "" at root
	Dir         string // absolute path to the skill folder
	SkillFile   string // absolute path to the SKILL.md
	Frontmatter metadata.Frontmatter
	Valid       bool
	Problems    []Diagnostic
}

DiscoveredSkill is one skill folder found by scanning a source (FR-001).

type DuplicateConflict

type DuplicateConflict struct {
	ID    string
	Paths []string // all participating in-repo paths, sorted
}

DuplicateConflict records two or more discovered skills whose normalized ids collide (FR-011).

type Options

type Options struct {
	MaxDepth   int             // 0 ⇒ unbounded (default)
	Include    []string        // path globs; empty ⇒ all
	Exclude    []string        // path globs, applied on top of the default ignore set
	IgnoreDirs map[string]bool // directory names to prune; nil ⇒ DefaultIgnoreDirs
	RootID     string          // identity for a root SKILL.md; "" ⇒ derived from the source base (R2/U1)
}

Options constrains a scan (FR-012).

type Result

type Result struct {
	Skills      []DiscoveredSkill
	Duplicates  []DuplicateConflict
	Diagnostics []Diagnostic // source-level (non-skill-specific) findings
}

Result is the deterministic outcome of scanning one source (FR-009).

func DiscoverAll

func DiscoverAll(root string, opts Options) (Result, error)

DiscoverAll recursively scans root and returns every skill folder found, with per-skill diagnostics and duplicate conflicts. It is pure (filesystem only): it returns a non-nil error only when root itself cannot be walked, never for a per-skill defect, which is recorded as data instead (FR-001..FR-012).

type Severity

type Severity string

Severity classifies a Diagnostic. An error-severity diagnostic marks a skill invalid (not installable by default); a warning does not.

const (
	// SeverityError marks a defect that makes a skill invalid.
	SeverityError Severity = "error"
	// SeverityWarning marks a non-fatal advisory (e.g. a name/folder mismatch).
	SeverityWarning Severity = "warning"
)

type Skill

type Skill struct {
	// Dir is the absolute directory containing SKILL.md.
	Dir string
	// RelDir is Dir relative to the search root (forward-slash, "." at root).
	RelDir string
	// Frontmatter is the parsed, validated SKILL.md frontmatter.
	Frontmatter metadata.Frontmatter
	// Body is the markdown body.
	Body []byte
	// Warnings carries non-fatal validation warnings (e.g. unknown keys).
	Warnings []string
}

Skill is a discovered, validated skill bundle.

func Discover

func Discover(root, explicitPath string) (Skill, error)

Discover locates the skill within root. When explicitPath is set, only that subpath is consulted (explicit path wins, FR-011); otherwise the tree is searched and exactly one SKILL.md must be present (FR-011, FR-013).