skill

type Lineage string

type Skill struct {
	Dir             string   // skill directory
	Path            string   // <Dir>/SKILL.md
	Name            string   // frontmatter name
	Description     string   // frontmatter description
	FrontmatterKeys []string // top-level frontmatter keys, sorted (for lint)
	Frontmatter     string   // raw YAML frontmatter block (between the --- lines)
	Body            string   // markdown body after the frontmatter

	// Lineage is the recognised `lineage:` declaration, LineageUnset when absent *or*
	// unrecognised, so a caller that ignores LineageRaw gets the strictest treatment.
	//
	// LineageRaw is the value as written, kept so an unrecognised one can be reported
	// verbatim rather than described. Unrecognised is therefore
	// `LineageRaw != "" && Lineage == LineageUnset` — derived rather than a second
	// boolean, because a bool's zero value would say "unrecognised" on the
	// FrontmatterErr path, where nothing was parsed and there is nothing to report.
	// That is the trap the note on FrontmatterErr describes, one field over.
	//
	// A bad value is not a load failure, for the same reason FrontmatterErr is not: one
	// malformed skill must not stop a caller walking a tree.
	Lineage    Lineage
	LineageRaw string
	Raw        string // full file contents
	Bytes      int    // byte size of Raw

	// FrontmatterErr is the error from parsing the YAML frontmatter, or nil when it
	// parsed. When it is non-nil, Name, Description and FrontmatterKeys are zero
	// because nothing could be read out of the block — they are not evidence that
	// those fields are absent from the file. A linter that reports "description is
	// empty" without checking this sends the reader to the wrong line.
	//
	// The underlying YAML error is kept verbatim: it locates the offending line and
	// column, which is the part a reader needs, and nothing classifies on it.
	FrontmatterErr error
}