skills

type Frontmatter struct {
	// Name is the unique skill identifier; it must match the skill's parent
	// directory name. Required.
	Name string `yaml:"name"`
	// Description states what the skill does and when to use it — the text an
	// agent reads to decide relevance. Required.
	Description string `yaml:"description"`
	// License names the license, or a bundled license file. Optional.
	License string `yaml:"license,omitempty"`
	// Compatibility states environment requirements (target product, system
	// packages, network access, ...). Optional.
	Compatibility string `yaml:"compatibility,omitempty"`
	// Metadata is an arbitrary string map for client-defined properties.
	Metadata map[string]string `yaml:"metadata,omitempty"`
	// AllowedTools is a space-separated list of pre-approved tools. Optional
	// and experimental; this package parses but does not enforce it.
	AllowedTools string `yaml:"allowed-tools,omitempty"`
}

type Repository struct {
	// contains filtered or unexported fields
}

type RepositoryConfig struct {
	MaxEntries          int
	MaxFrontmatterBytes int64
	MaxSkillBytes       int64
}

type ResourceSource interface {
	Source
	// OpenResource opens one bundled resource beneath the exact skill root. It
	// must reject absolute paths, traversal, and symlink escape according to the
	// source's trust boundary and return a non-nil regular file on success.
	// The source validates the owning skill in this same operation. An absent
	// skill returns ErrSkillNotFound; a missing resource in an existing skill
	// returns fs.ErrNotExist without ErrSkillNotFound. Failed opens close any
	// acquired file; successful callers own and close the returned file.
	OpenResource(ctx context.Context, name, resource string) (fs.File, error)
}

type Skill struct {
	Frontmatter
	Instructions string
}

type Source interface {
	// List returns detached, valid summaries in the implementation's stable
	// discovery order. Invalid skill bundles may be skipped, but repository I/O,
	// permission, and context failures must be returned rather than disguised as
	// an empty source.
	List(ctx context.Context) ([]Summary, error)
	// Lookup checks one name's ownership and metadata without loading its
	// instructions or resources. An absent bundle returns ErrSkillNotFound;
	// invalid metadata returns ErrInvalidSkill. Access and cancellation errors
	// remain distinct from both. A valid summary does not guarantee that the
	// full document fits Load's limits or passes its validation.
	Lookup(ctx context.Context, name string) (Summary, error)
	// Load validates and returns one complete skill by exact name. The caller owns
	// the returned value. An absent skill returns ErrSkillNotFound; malformed
	// bundles, I/O errors, and cancellation must not be classified as absence.
	Load(ctx context.Context, name string) (*Skill, error)
}

type Summary struct {
	Name        string
	Description string
}