skills

package
v0.1.0-beta.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 18, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BehavioralChanges

func BehavioralChanges(old, new *Fingerprint) []string

BehavioralChanges compares two fingerprints and returns human-readable changes.

func CheckUpdatesBackground

func CheckUpdatesBackground(registryDir string, logger *slog.Logger)

CheckUpdatesBackground runs update checks in a background goroutine. Results are written to the cache file for display on next CLI command.

func ContentHashFile

func ContentHashFile(path string) (string, error)

ContentHashFile computes a SHA-256 hash of a file.

func DeleteOrigin

func DeleteOrigin(skillDir string) error

DeleteOrigin removes the .origin.json file from a skill directory.

func FetchAndCompare

func FetchAndCompare(repo, ref string, currentSHA string, logger *slog.Logger) (string, bool, error)

FetchAndCompare fetches the latest from a remote and compares with current.

func FormatFindings

func FormatFindings(findings []SecurityFinding) string

FormatFindings returns a human-readable summary of security findings.

func FormatUpdateNotice

func FormatUpdateNotice() string

FormatUpdateNotice returns a user-friendly message about available updates.

func HasOrigin

func HasOrigin(skillDir string) bool

HasOrigin checks if a skill directory has an .origin.json file.

func IsSemVerConstraint

func IsSemVerConstraint(ref string) bool

IsSemVerConstraint returns true if the ref looks like a semver constraint.

func ListRemoteTags

func ListRemoteTags(repoPath string) ([]string, error)

ListRemoteTags returns all tags from a remote repository.

func LockFilePath

func LockFilePath() string

LockFilePath returns the default path to skills.lock.yaml.

func ResolveSemVerConstraint

func ResolveSemVerConstraint(constraintStr string, tags []string) (string, error)

ResolveSemVerConstraint finds the best matching tag for a constraint.

func SafeRepoPath

func SafeRepoPath(path string) error

SafeRepoPath validates a path component to prevent directory traversal.

func ShouldCheckUpdates

func ShouldCheckUpdates() bool

ShouldCheckUpdates returns false if update checks are disabled.

func SkillsConfigPath

func SkillsConfigPath() string

SkillsConfigPath returns the default path to skills.yaml.

func UpdateCachePath

func UpdateCachePath() string

UpdateCachePath returns the path to the cached update status file.

func WriteLockFile

func WriteLockFile(path string, lf *LockFile) error

WriteLockFile writes skills.lock.yaml atomically. Keys are sorted for minimal merge conflicts.

func WriteOrigin

func WriteOrigin(skillDir string, origin *Origin) error

WriteOrigin writes the .origin.json file to a skill directory.

func WriteUpdateCache

func WriteUpdateCache(status *UpdateStatus) error

WriteUpdateCache writes the update status to cache.

Types

type CloneResult

type CloneResult struct {
	RepoPath  string
	CommitSHA string
	Skills    []DiscoveredSkill
}

CloneResult contains the result of a clone + discovery operation.

func CloneAndDiscover

func CloneAndDiscover(repo, ref, subPath string, logger *slog.Logger) (*CloneResult, error)

CloneAndDiscover clones a repo and discovers all SKILL.md files.

type DiscoveredSkill

type DiscoveredSkill struct {
	Name        string
	Path        string // Relative path from repo root to SKILL.md directory
	Skill       *registry.AgentSkill
	ContentHash string
}

DiscoveredSkill represents a SKILL.md found in a cloned repo.

type Fingerprint

type Fingerprint struct {
	ContentHash string   `json:"contentHash" yaml:"content_hash"`
	ToolsHash   string   `json:"toolsHash" yaml:"tools_hash"`
	Tools       []string `json:"tools,omitempty" yaml:"tools,omitempty"`
	WorkflowLen int      `json:"workflowSteps" yaml:"workflow_steps"`
}

Fingerprint captures the behavioral identity of a skill.

func ComputeFingerprint

func ComputeFingerprint(skill *registry.AgentSkill) *Fingerprint

ComputeFingerprint generates a behavioral fingerprint for a skill.

type ImportOptions

type ImportOptions struct {
	Repo       string
	Ref        string
	Path       string
	Trust      bool   // Skip security scan confirmation
	NoActivate bool   // Import as draft instead of active
	Force      bool   // Overwrite existing skills
	Rename     string // Rename the skill on import
}

ImportOptions controls the import behavior.

type ImportResult

type ImportResult struct {
	Imported []ImportedSkill
	Skipped  []SkippedSkill
	Warnings []string
}

ImportResult contains the results of an import operation.

type ImportedSkill

type ImportedSkill struct {
	Name     string
	Path     string
	Origin   *Origin
	Findings []SecurityFinding
}

ImportedSkill records a successfully imported skill.

type Importer

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

Importer orchestrates the skill import process.

func NewImporter

func NewImporter(store *registry.Store, registryDir, lockPath string, logger *slog.Logger) *Importer

NewImporter creates a new skill importer.

func (*Importer) Import

func (imp *Importer) Import(opts ImportOptions) (*ImportResult, error)

Import clones a repo, discovers skills, validates, scans, and imports.

func (*Importer) Info

func (imp *Importer) Info(skillName string) (*SkillInfo, error)

Info returns details about a skill's origin and update status.

func (*Importer) Pin

func (imp *Importer) Pin(skillName, ref string) error

Pin updates a skill's ref and disables auto-update.

func (*Importer) Remove

func (imp *Importer) Remove(skillName string) error

Remove removes an imported skill and cleans up origin and lock entries.

func (*Importer) Update

func (imp *Importer) Update(skillName string, dryRun, force bool) (*ImportResult, error)

Update fetches latest for a skill and applies changes.

type LockFile

type LockFile struct {
	Sources map[string]LockedSource `yaml:"sources"`
}

LockFile represents skills.lock.yaml — pins exact versions of imported skills.

func ReadLockFile

func ReadLockFile(path string) (*LockFile, error)

ReadLockFile reads and parses skills.lock.yaml.

func (*LockFile) FindSkillSource

func (lf *LockFile) FindSkillSource(skillName string) (string, *LockedSource, bool)

FindSkillSource finds the source name for a given skill.

func (*LockFile) RemoveSkill

func (lf *LockFile) RemoveSkill(skillName string)

RemoveSkill removes a single skill from the lock file, cleaning up the source if empty.

func (*LockFile) RemoveSource

func (lf *LockFile) RemoveSource(name string)

RemoveSource removes a source from the lock file.

func (*LockFile) SetSource

func (lf *LockFile) SetSource(name string, src LockedSource)

SetSource updates or adds a source in the lock file.

type LockedSkill

type LockedSkill struct {
	Path        string       `yaml:"path"`
	ContentHash string       `yaml:"content_hash"`
	Fingerprint *Fingerprint `yaml:"fingerprint,omitempty"`
}

LockedSkill records per-skill metadata within a source.

type LockedSource

type LockedSource struct {
	Repo        string                 `yaml:"repo"`
	Ref         string                 `yaml:"ref"`
	ResolvedRef string                 `yaml:"resolved_ref,omitempty"`
	CommitSHA   string                 `yaml:"commit_sha"`
	FetchedAt   time.Time              `yaml:"fetched_at"`
	ContentHash string                 `yaml:"content_hash"`
	Skills      map[string]LockedSkill `yaml:"skills"`
}

LockedSource records the resolved state of a skill source.

type Origin

type Origin struct {
	Repo        string       `json:"repo"`
	Ref         string       `json:"ref"`
	Path        string       `json:"path,omitempty"`
	CommitSHA   string       `json:"commitSha"`
	ImportedAt  time.Time    `json:"importedAt"`
	ContentHash string       `json:"contentHash"`
	Fingerprint *Fingerprint `json:"fingerprint,omitempty"`
}

Origin tracks the remote source of an imported skill. Stored as .origin.json alongside the SKILL.md file.

func ReadOrigin

func ReadOrigin(skillDir string) (*Origin, error)

ReadOrigin reads the .origin.json file from a skill directory.

type ScanResult

type ScanResult struct {
	SkillName string            `json:"skillName"`
	Findings  []SecurityFinding `json:"findings"`
	Safe      bool              `json:"safe"`
}

ScanResult contains the security scan results for a skill.

func ScanSkill

func ScanSkill(sk *registry.AgentSkill) *ScanResult

ScanSkill checks a skill for dangerous patterns in its workflow and body.

type SecurityFinding

type SecurityFinding struct {
	StepID      string `json:"stepId"`
	Pattern     string `json:"pattern"`
	Description string `json:"description"`
	Severity    string `json:"severity"` // "warning" or "danger"
}

SecurityFinding represents a potentially dangerous pattern found in a skill.

type SkillDefaults

type SkillDefaults struct {
	AutoUpdate     bool   `yaml:"auto_update" json:"autoUpdate"`
	UpdateInterval string `yaml:"update_interval" json:"updateInterval"`
}

SkillDefaults defines global defaults for skill sources.

type SkillInfo

type SkillInfo struct {
	Name        string    `json:"name"`
	Origin      *Origin   `json:"origin,omitempty"`
	IsRemote    bool      `json:"isRemote"`
	UpdateAvail bool      `json:"updateAvailable"`
	LatestSHA   string    `json:"latestSha,omitempty"`
	LastChecked time.Time `json:"lastChecked,omitempty"`
}

SkillInfo returns details about an imported skill.

type SkillSource

type SkillSource struct {
	Name           string `yaml:"name" json:"name"`
	Repo           string `yaml:"repo" json:"repo"`
	Ref            string `yaml:"ref,omitempty" json:"ref,omitempty"`
	Path           string `yaml:"path,omitempty" json:"path,omitempty"`
	AutoUpdate     *bool  `yaml:"auto_update,omitempty" json:"autoUpdate,omitempty"`
	UpdateInterval string `yaml:"update_interval,omitempty" json:"updateInterval,omitempty"`
}

SkillSource defines a remote skill source in skills.yaml.

type SkillUpdate

type SkillUpdate struct {
	CurrentSHA string `yaml:"current_sha"`
	LatestSHA  string `yaml:"latest_sha"`
	Repo       string `yaml:"repo"`
	Ref        string `yaml:"ref"`
}

SkillUpdate describes an available update for a skill.

type SkillsConfig

type SkillsConfig struct {
	Defaults SkillDefaults `yaml:"defaults,omitempty" json:"defaults,omitempty"`
	Sources  []SkillSource `yaml:"sources" json:"sources"`
}

SkillsConfig represents the skills.yaml file.

func DefaultSkillsConfig

func DefaultSkillsConfig() *SkillsConfig

DefaultSkillsConfig returns a config with sensible defaults.

func LoadSkillsConfig

func LoadSkillsConfig(path string) (*SkillsConfig, error)

LoadSkillsConfig reads and parses a skills.yaml file.

func (*SkillsConfig) EffectiveAutoUpdate

func (c *SkillsConfig) EffectiveAutoUpdate(src *SkillSource) bool

EffectiveAutoUpdate returns the auto_update setting for a source, falling back to the global default.

func (*SkillsConfig) EffectiveUpdateInterval

func (c *SkillsConfig) EffectiveUpdateInterval(src *SkillSource) time.Duration

EffectiveUpdateInterval returns the update_interval for a source, falling back to the global default.

type SkippedSkill

type SkippedSkill struct {
	Name   string
	Reason string
}

SkippedSkill records a skill that was skipped during import.

type UpdateStatus

type UpdateStatus struct {
	CheckedAt time.Time              `yaml:"checked_at"`
	Updates   map[string]SkillUpdate `yaml:"updates,omitempty"`
	Errors    []string               `yaml:"errors,omitempty"`
}

UpdateStatus records the result of a background update check.

func ReadUpdateCache

func ReadUpdateCache() (*UpdateStatus, error)

ReadUpdateCache reads the cached update status.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL