Documentation
¶
Overview ¶
Package skills provides the skills.sh registry client, source parsing, lock file management, and skill installation logic for the sl skill command.
It integrates with Vercel's skills.sh registry via public HTTP APIs:
- skills.sh/api/search — skill discovery by keyword
- add-skill.vercel.sh/audit — security risk assessments (ATH, Socket, Snyk)
- add-skill.vercel.sh/t — install/remove telemetry
- api.github.com — GitHub Trees API for repo skill enumeration
- raw.githubusercontent.com — SKILL.md content fetch
Skills are installed to agent-specific directories resolved from the agent registry and tracked in a Vercel-compatible skills-lock.json.
Index ¶
- func AddSkill(lock *LocalSkillLockFile, name string, entry LocalSkillLockEntry)
- func BuildTelemetryParams(source string, skillNames []string, agents []string) map[string]string
- func ComputeFolderHash(dir string) (string, error)
- func InstallSkill(name string, content []byte, agentPaths []string, lockPath string, ...) error
- func IsSkillInstalled(name, lockPath string) bool
- func RemoveSkill(lock *LocalSkillLockFile, name string)
- func Track(auditURL, event string, params map[string]string, version string)
- func TrackSync(auditURL, event string, params map[string]string, version string) error
- func UninstallSkill(name string, agentPaths []string, lockPath string) error
- func ValidateSkillName(name string) error
- func WriteLocalLock(path string, lock *LocalSkillLockFile) error
- type Client
- func (c *Client) FetchAudit(source string, slugs []string) (map[string]*SkillAuditResult, error)
- func (c *Client) FetchRepoTree(owner, repo, ref string) ([]GitHubTreeEntry, error)
- func (c *Client) FetchSkillContent(owner, repo, ref, skillPath string) ([]byte, error)
- func (c *Client) Search(query string, limit int) ([]SkillSearchResult, error)
- type GitHubTreeEntry
- type LocalSkillLockEntry
- type LocalSkillLockFile
- type PartnerAudit
- type SkillAuditResult
- type SkillMetadata
- type SkillSearchResult
- type SkillSource
- type SourceType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddSkill ¶
func AddSkill(lock *LocalSkillLockFile, name string, entry LocalSkillLockEntry)
AddSkill adds or updates a skill entry in the lock file.
func BuildTelemetryParams ¶
BuildTelemetryParams creates the standard telemetry params for an event.
func ComputeFolderHash ¶
ComputeFolderHash computes a deterministic SHA-256 hash of all files in dir. Files are sorted by relative path; each file contributes its relative path and contents to the running hash. Directories .git and node_modules are skipped.
func InstallSkill ¶
func InstallSkill(name string, content []byte, agentPaths []string, lockPath string, source *SkillSource) error
InstallSkill writes SKILL.md content to each agent's skills directory and updates the lock file.
func IsSkillInstalled ¶
IsSkillInstalled checks if a skill is present in the lock file.
func RemoveSkill ¶
func RemoveSkill(lock *LocalSkillLockFile, name string)
RemoveSkill removes a skill entry from the lock file.
func Track ¶
Track sends a fire-and-forget telemetry ping to skills.sh. It runs in a goroutine and never blocks the caller. Telemetry is skipped if disabled via env vars, running in CI, or source repo is private.
func UninstallSkill ¶
UninstallSkill removes a skill from all agent directories and the lock file.
func ValidateSkillName ¶
ValidateSkillName rejects names that could cause path traversal or escape the skills directory. Called before any filesystem operation.
func WriteLocalLock ¶
func WriteLocalLock(path string, lock *LocalSkillLockFile) error
WriteLocalLock writes the lock file with skills sorted alphabetically, 2-space indent, and trailing newline.
Types ¶
type Client ¶
type Client struct {
SearchURL string // skills.sh base URL
AuditURL string // add-skill.vercel.sh base URL
GitHubURL string // api.github.com base URL
RawGHURL string // raw.githubusercontent.com base URL
HTTPClient *http.Client
}
Client is an HTTP client for the skills.sh and GitHub APIs.
func NewClient ¶
func NewClient() *Client
NewClient creates a Client with base URLs from env vars (for testability).
func (*Client) FetchAudit ¶
FetchAudit fetches security audit data for one or more skills.
func (*Client) FetchRepoTree ¶
func (c *Client) FetchRepoTree(owner, repo, ref string) ([]GitHubTreeEntry, error)
FetchRepoTree fetches the full recursive tree for a repository.
func (*Client) FetchSkillContent ¶
FetchSkillContent fetches the raw SKILL.md content from GitHub.
type GitHubTreeEntry ¶
type GitHubTreeEntry struct {
Path string `json:"path"`
Mode string `json:"mode"`
Type string `json:"type"`
SHA string `json:"sha"`
Size int `json:"size"`
}
GitHubTreeEntry is a single entry from the GitHub Trees API.
type LocalSkillLockEntry ¶
type LocalSkillLockEntry struct {
Source string `json:"source"`
Ref string `json:"ref,omitempty"`
SourceType string `json:"sourceType"`
ComputedHash string `json:"computedHash"`
}
LocalSkillLockEntry is a single entry in skills-lock.json. Schema matches official Vercel format.
type LocalSkillLockFile ¶
type LocalSkillLockFile struct {
Version int `json:"version"`
Skills map[string]LocalSkillLockEntry `json:"skills"`
}
LocalSkillLockFile is the skills-lock.json file. Matches official Vercel schema v1.
func ReadLocalLock ¶
func ReadLocalLock(path string) (*LocalSkillLockFile, error)
ReadLocalLock reads and parses skills-lock.json. Returns an empty lock file struct if the file does not exist. Returns an error on invalid JSON.
type PartnerAudit ¶
type PartnerAudit struct {
Risk string `json:"risk"`
Alerts int `json:"alerts"`
Score int `json:"score"`
AnalyzedAt time.Time `json:"analyzedAt"`
}
PartnerAudit is security audit data for a single partner.
type SkillAuditResult ¶
type SkillAuditResult struct {
Slug string `json:"slug,omitempty"`
ATH *PartnerAudit `json:"ath,omitempty"`
Socket *PartnerAudit `json:"socket,omitempty"`
Snyk *PartnerAudit `json:"snyk,omitempty"`
}
SkillAuditResult is audit results for a single skill across all partners.
type SkillMetadata ¶
type SkillMetadata struct {
Name string `yaml:"name" json:"name"`
Description string `yaml:"description" json:"description"`
Slug string `yaml:"-" json:"slug,omitempty"`
Source string `yaml:"-" json:"source,omitempty"`
RepoPath string `yaml:"-" json:"-"` // path to SKILL.md within the repo (set during discovery)
Internal bool `yaml:"internal,omitempty" json:"-"`
}
SkillMetadata is parsed from SKILL.md YAML frontmatter.
func DiscoverSkills ¶
func DiscoverSkills(client *Client, source *SkillSource) ([]SkillMetadata, error)
DiscoverSkills enumerates available skills in a repository. For GitHub sources, uses the Trees API (fast path). For git URLs or on GitHub 404, falls back to git clone.
func ParseSkillFrontmatter ¶
func ParseSkillFrontmatter(content []byte) (*SkillMetadata, error)
ParseSkillFrontmatter parses YAML frontmatter from SKILL.md content. Expects --- delimited frontmatter with at least name and description fields.
type SkillSearchResult ¶
type SkillSearchResult struct {
ID string `json:"id"`
Name string `json:"name"`
Source string `json:"source"`
Installs int `json:"installs"`
}
SkillSearchResult is a single result from the search API.
type SkillSource ¶
type SkillSource struct {
Owner string
Repo string
SkillFilter string // optional: specific skill name from @skill syntax
Ref string // git ref, defaults to "main"
Type SourceType
URL string // original URL for git type
}
SkillSource is a parsed representation of a user-provided skill identifier.
func ParseSource ¶
func ParseSource(input string) (*SkillSource, error)
ParseSource parses a skill source identifier into a structured SkillSource.
Supported formats:
- owner/repo → GitHub shorthand
- owner/repo@skill → GitHub shorthand with skill filter
- https://github.com/owner/repo.git → full HTTPS URL
- git@github.com:owner/repo.git → SSH URL
func (*SkillSource) SourceString ¶
func (s *SkillSource) SourceString() string
SourceString returns the canonical "owner/repo" string.
type SourceType ¶
type SourceType string
SourceType indicates how to fetch the skill content.
const ( SourceTypeGitHub SourceType = "github" SourceTypeGit SourceType = "git" )
Source Files