registry

Documentation

Overview

Package registry loads and queries the skill index.

The source of truth is one JSON shard per skill under skills/. CI compiles the shards into a single index published on the gh-pages branch. At runtime Load prefers a fresh local cache, revalidates with the remote index, and falls back to the cache and finally to the shards embedded in the binary, so it works offline.

Index

• func Validate(e Entry) error
• func ValidateInstall(e Entry) error
• type Entry
  • func BuildIndex(root string) ([]Entry, error)
  • func Cached() ([]Entry, error)
  • func Find(ctx context.Context, name string) (Entry, bool, error)
  • func Load(ctx context.Context) ([]Entry, error)
  • func Search(ctx context.Context, query string) ([]Entry, error)
  • func (e Entry) KindOrDefault() string
• type HookSpec
• type MCPSpec

Functions

func Validate

func Validate(e Entry) error

Validate is the full registry-entry check: descriptive metadata plus everything ValidateInstall covers. Registry shards and the compiled index use this.

func ValidateInstall

func ValidateInstall(e Entry) error

ValidateInstall checks the fields skillet needs to install an entry safely. For a skill, command, or hook that means a safe single-component name, an http(s) repo, a contained path, and a valid kind, ref, and cksum. An mcp entry is a server spec rather than a repo, so it is validated separately. It does not require descriptive metadata, so it also validates an untrusted lockfile entry before it reaches git or the filesystem.

Types

type Entry

type Entry struct {
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Repo        string    `json:"repo"`
	Path        string    `json:"path"`
	Author      string    `json:"author"`
	Tags        []string  `json:"tags"`
	Kind        string    `json:"kind,omitempty"`  // skill (default), command, hook, or mcp
	Ref         string    `json:"ref,omitempty"`   // commit SHA or tag to pin the install to
	Cksum       string    `json:"cksum,omitempty"` // sha256: tree hash, verified on install
	Hook        *HookSpec `json:"hook,omitempty"`  // required for kind hook: how to register it
	MCP         *MCPSpec  `json:"mcp,omitempty"`   // required for kind mcp: the server to register
}

Entry is a single curated skill in the registry.

func BuildIndex

func BuildIndex(root string) ([]Entry, error)

BuildIndex reads every *.json shard under root's per-kind directories (skills, commands, hooks), validates and de-duplicates them, and returns the sorted index. Used by the cmd/buildindex compiler.

func Cached

func Cached() ([]Entry, error)

Cached returns the index from the local cache, or the embedded baseline if no cache exists. It never touches the network, so it is safe for latency-sensitive paths like shell completion.

func Find

func Find(ctx context.Context, name string) (Entry, bool, error)

Find returns the entry whose name matches (case-insensitively).

func Load

func Load(ctx context.Context) ([]Entry, error)

Load returns the skill index. It prefers a fresh on-disk cache, then revalidates with the remote index, and falls back to the cache and finally to the embedded baseline. It does not fail for a transient network problem as long as the embedded shards parse.

func Search

func Search(ctx context.Context, query string) ([]Entry, error)

Search returns entries matching query, ranked by relevance: an exact or prefix name match beats a name substring, which beats a tag, which beats the description, which beats a fuzzy (subsequence) name match. An empty query returns every entry sorted by name.

func (Entry) KindOrDefault

func (e Entry) KindOrDefault() string

KindOrDefault returns the entry's kind, defaulting to "skill".

type HookSpec

type HookSpec struct {
	Event   string `json:"event"`
	Matcher string `json:"matcher,omitempty"`
}

HookSpec is how a hook registers in ~/.claude/settings.json. The installed script is added under the named event; an empty matcher matches everything.

type MCPSpec

type MCPSpec struct {
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	URL     string            `json:"url,omitempty"`
}

MCPSpec describes an MCP server to register in a tool's MCP config. A stdio server sets Command (with optional Args and Env); a remote server sets URL instead. Exactly one of Command or URL is set.