skills

package
v0.0.26 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 29 Imported by: 3

Documentation

Overview

Package skills provides OCI artifact types, media types, local storage, and remote registry operations for ToolHive skill packages.

A skill is an OCI artifact containing MCP server configuration, prompt files, and metadata. This package defines the constants, data structures, storage layer, and registry client that the rest of the ToolHive ecosystem uses to package, push, pull, and cache skills as OCI images.

Media Types and Constants

Standard OCI media types and ToolHive-specific annotation/label keys: 

// Artifact type identifies a skill manifest
skills.ArtifactTypeSkill // "dev.toolhive.skills.v1"

// Annotations carry metadata in manifests
skills.AnnotationSkillName
skills.AnnotationSkillVersion

// Labels carry metadata in OCI image configs
skills.LabelSkillName
skills.LabelSkillFiles

Registry Client

The Registry type implements RegistryClient for pushing and pulling skill artifacts to/from OCI-compliant registries (GHCR, ECR, Docker Hub, etc.). It uses ORAS for registry operations and the Docker credential store for authentication by default: 

reg, err := skills.NewRegistry()
// Push an artifact
err = reg.Push(ctx, store, indexDigest, "ghcr.io/myorg/my-skill:v1.0.0")
// Pull an artifact
digest, err := reg.Pull(ctx, store, "ghcr.io/myorg/my-skill:v1.0.0")

Use functional options to customise behaviour: 

reg, err := skills.NewRegistry(
    skills.WithPlainHTTP(true),           // for local dev registries
    skills.WithCredentialStore(myStore),   // custom auth
)

Stability

This package is Alpha. Breaking changes are possible between minor versions.

Index

Constants

View Source 
const (
	// MaxTarFileSize is the maximum size of a single file in a tar archive (100MB).
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.MaxTarFileSize.
	MaxTarFileSize = artifact.MaxTarFileSize
	// MaxDecompressedSize is the maximum size of decompressed data (100MB).
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.MaxDecompressedSize.
	MaxDecompressedSize = artifact.MaxDecompressedSize
	// MaxManifestSize is the maximum size of a manifest (1MB).
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.MaxManifestSize.
	MaxManifestSize = artifact.MaxManifestSize
	// MaxBlobSize is the maximum size of a blob (100MB).
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.MaxBlobSize.
	MaxBlobSize = artifact.MaxBlobSize
)

Size limit constants re-exported from the artifact package.

View Source 
const (
	// OSLinux is the Linux OS identifier used in OCI platform specs.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.OSLinux.
	OSLinux = artifact.OSLinux
	// ArchAMD64 is the x86-64 architecture identifier used in OCI platform specs.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.ArchAMD64.
	ArchAMD64 = artifact.ArchAMD64
	// ArchARM64 is the 64-bit ARM architecture identifier used in OCI platform specs.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.ArchARM64.
	ArchARM64 = artifact.ArchARM64
)

OS and architecture constants for OCI platform specifications.

View Source 
const (
	// AnnotationSkillName is the annotation key for skill name.
	AnnotationSkillName = "dev.toolhive.skills.name"

	// AnnotationSkillDescription is the annotation key for skill description.
	AnnotationSkillDescription = "dev.toolhive.skills.description"

	// AnnotationSkillVersion is the annotation key for skill version.
	AnnotationSkillVersion = "dev.toolhive.skills.version"

	// AnnotationSkillRequires is the annotation key for skill external dependencies (JSON array of OCI references).
	AnnotationSkillRequires = "dev.toolhive.skills.requires"
)

Annotation keys for skill metadata in manifests.

View Source 
const (
	// LabelSkillName is the label key for skill name.
	LabelSkillName = "dev.toolhive.skills.name"

	// LabelSkillDescription is the label key for skill description.
	LabelSkillDescription = "dev.toolhive.skills.description"

	// LabelSkillVersion is the label key for skill version.
	LabelSkillVersion = "dev.toolhive.skills.version"

	// LabelSkillAllowedTools is the label key for allowed tools (JSON array).
	LabelSkillAllowedTools = "dev.toolhive.skills.allowedTools"

	// LabelSkillLicense is the label key for skill license.
	LabelSkillLicense = "dev.toolhive.skills.license"

	// LabelSkillFiles is the label key for skill files (JSON array).
	LabelSkillFiles = "dev.toolhive.skills.files"
)

Label keys for skill metadata in OCI image config.

View Source 
const (
	// ArtifactTypeSkill identifies skill artifacts in manifests.
	ArtifactTypeSkill = "dev.toolhive.skills.v1"
)

Artifact type for skill identification.

View Source 
const SkillFileName = "SKILL.md"

SkillFileName is the required metadata file name for a skill directory.

Variables

View Source 
var (
	// DefaultTarOptions returns default options for reproducible tar archives.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.DefaultTarOptions.
	DefaultTarOptions = artifact.DefaultTarOptions
	// CreateTar creates a reproducible tar archive from the given files.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.CreateTar.
	CreateTar = artifact.CreateTar
	// ExtractTar extracts files from a tar archive.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.ExtractTar.
	ExtractTar = artifact.ExtractTar
	// ExtractTarWithLimit extracts files from a tar archive with a per-file size limit.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.ExtractTarWithLimit.
	ExtractTarWithLimit = artifact.ExtractTarWithLimit
)

Function forwarding for tar primitives.

View Source 
var (
	// DefaultGzipOptions returns default options for reproducible gzip compression.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.DefaultGzipOptions.
	DefaultGzipOptions = artifact.DefaultGzipOptions
	// Compress creates a reproducible gzip compressed byte slice.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.Compress.
	Compress = artifact.Compress
	// Decompress decompresses gzip data.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.Decompress.
	Decompress = artifact.Decompress
	// DecompressWithLimit decompresses gzip data with a size limit.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.DecompressWithLimit.
	DecompressWithLimit = artifact.DecompressWithLimit
	// CompressTar creates a reproducible .tar.gz from the given files.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.CompressTar.
	CompressTar = artifact.CompressTar
	// DecompressTar extracts files from a .tar.gz archive.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.DecompressTar.
	DecompressTar = artifact.DecompressTar
)

Function forwarding for gzip primitives.

View Source 
var (
	// PlatformString returns the platform in "os/arch" or "os/arch/variant" format.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.PlatformString.
	PlatformString = artifact.PlatformString
	// ParsePlatform parses a platform string in "os/arch" or "os/arch/variant" format.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.ParsePlatform.
	ParsePlatform = artifact.ParsePlatform
	// DefaultPlatforms are the default platforms for artifacts.
	// Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.DefaultPlatforms.
	DefaultPlatforms = artifact.DefaultPlatforms
)

Function forwarding for platform helpers.

View Source 
var (
	// ErrInvalidSkillDir indicates the skill directory is missing, not a
	// directory, or otherwise unsafe to read (e.g. contains path traversal).
	ErrInvalidSkillDir = errors.New("invalid skill directory")

	// ErrSkillMDMissing indicates SKILL.md is not present in the skill
	// directory.
	ErrSkillMDMissing = errors.New("SKILL.md missing")

	// ErrInvalidFrontmatter indicates the SKILL.md YAML frontmatter is
	// missing, malformed, oversized, or missing required fields such as
	// the skill name.
	ErrInvalidFrontmatter = errors.New("invalid SKILL.md frontmatter")

	// ErrTooManyFiles indicates the skill directory exceeds the maximum
	// allowed number of files.
	ErrTooManyFiles = errors.New("too many files in skill directory")

	// ErrSkillTooLarge indicates the skill directory exceeds the maximum
	// allowed total size.
	ErrSkillTooLarge = errors.New("skill directory too large")

	// ErrInvalidSkillFile indicates a per-file issue inside the skill
	// directory: a symlink, a non-regular file, or an unreadable entry.
	ErrInvalidSkillFile = errors.New("invalid skill file")
)

Sentinel errors returned (wrapped) by the packager so callers can classify failures with errors.Is instead of matching error message strings. The underlying error message is preserved at each call site via fmt.Errorf with %w; only the classification is added.

Functions

func DefaultStoreRoot 

func DefaultStoreRoot() string

DefaultStoreRoot returns the default store root directory using XDG base directory conventions.

func ParseRequiresAnnotation 

func ParseRequiresAnnotation(annotations map[string]string) []string

ParseRequiresAnnotation parses skill dependency references from manifest annotations. Returns nil if the annotation is missing or invalid.

func StoreRoot 

func StoreRoot(dataHome string) string

StoreRoot returns the skills store root within the given data home directory. This is the injectable, testable form. For the standard XDG location, use DefaultStoreRoot.

Types

type FileEntry 

type FileEntry = artifact.FileEntry

FileEntry represents a file to include in a tar archive. Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.FileEntry.

type GzipOptions 

type GzipOptions = artifact.GzipOptions

GzipOptions configures reproducible gzip compression. Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.GzipOptions.

type PackageOptions 

type PackageOptions struct {
	// Epoch is the timestamp to use for reproducible builds.
	Epoch time.Time

	// Platforms specifies target platforms for the image index.
	// If empty, defaults to DefaultPlatforms.
	Platforms []ocispec.Platform
}

PackageOptions configures skill packaging.

func DefaultPackageOptions 

func DefaultPackageOptions() PackageOptions

DefaultPackageOptions returns default packaging options. Respects SOURCE_DATE_EPOCH for reproducible builds.

type PackageResult 

type PackageResult struct {
	IndexDigest    digest.Digest
	ManifestDigest digest.Digest
	ConfigDigest   digest.Digest
	LayerDigest    digest.Digest
	Config         *SkillConfig
	Platforms      []ocispec.Platform
}

PackageResult contains the result of packaging a skill.

type Packager 

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

Packager creates reproducible OCI artifacts from skill directories.

func NewPackager 

func NewPackager(store *Store) *Packager

NewPackager creates a new packager with the given store. Panics if store is nil.

func (*Packager) Package 

func (p *Packager) Package(ctx context.Context, skillDir string, opts PackageOptions) (*PackageResult, error)

Package packages a skill directory into an OCI artifact in the local store.

type Registry 

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

Registry provides operations for pushing and pulling skills from OCI registries.

func NewRegistry 

func NewRegistry(opts ...RegistryOption) (*Registry, error)

NewRegistry creates a new registry client with the given options. By default it uses the Docker credential store for authentication.

func (*Registry) Pull 

func (r *Registry) Pull(ctx context.Context, store *Store, ref string) (digest.Digest, error)

Pull pulls a skill artifact from a remote registry to the local store. Returns the digest of the pulled artifact (index or manifest).

func (*Registry) Push 

func (r *Registry) Push(ctx context.Context, store *Store, artifactDigest digest.Digest, ref string) error

Push pushes a skill artifact from the local store to a remote registry. The digest can be either an index digest or a manifest digest.

type RegistryClient 

type RegistryClient interface {
	// Push pushes an artifact from the local store to a remote registry.
	Push(ctx context.Context, store *Store, manifestDigest digest.Digest, ref string) error

	// Pull pulls an artifact from a remote registry into the local store.
	Pull(ctx context.Context, store *Store, ref string) (digest.Digest, error)
}

RegistryClient provides remote OCI registry operations for skills.

type RegistryOption 

type RegistryOption func(*Registry)

RegistryOption configures a Registry.

func WithCredentialStore 

func WithCredentialStore(store credentials.Store) RegistryOption

WithCredentialStore sets a custom credential store for registry authentication. If not provided, the default Docker credential store is used.

func WithPlainHTTP 

func WithPlainHTTP(enabled bool) RegistryOption

WithPlainHTTP configures whether the registry client uses plain HTTP (insecure) connections.

type SkillConfig 

type SkillConfig struct {
	Name          string            `json:"name"`
	Description   string            `json:"description"`
	Version       string            `json:"version,omitempty"`
	AllowedTools  []string          `json:"allowedTools,omitempty"`
	License       string            `json:"license,omitempty"`
	Compatibility string            `json:"compatibility,omitempty"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	Files         []string          `json:"files"`
}

SkillConfig represents skill metadata extracted from OCI image config labels.

func SkillConfigFromImageConfig 

func SkillConfigFromImageConfig(imgConfig *ocispec.Image) (*SkillConfig, error)

SkillConfigFromImageConfig extracts SkillConfig from OCI image config labels.

type SkillPackager 

type SkillPackager interface {
	// Package packages a skill directory into an OCI artifact in the local store.
	Package(ctx context.Context, skillDir string, opts PackageOptions) (*PackageResult, error)
}

SkillPackager creates OCI artifacts from skill directories.

type Store 

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

Store provides local OCI artifact storage backed by an OCI Image Layout.

func NewStore 

func NewStore(root string) (*Store, error)

NewStore creates a new local OCI store at the given root directory. The directory is initialized as an OCI Image Layout with blobs/, oci-layout, and index.json.

func (*Store) DeleteBuild added in v0.0.14 

func (s *Store) DeleteBuild(ctx context.Context, tag string) error

DeleteBuild removes a tag and, if no other tag shares the same digest, deletes all associated blobs (config, layers, manifest, and index if applicable). Use DeleteTag when tag-only removal is desired and blob cleanup is not needed.

func (*Store) DeleteTag added in v0.0.14 

func (s *Store) DeleteTag(ctx context.Context, tag string) error

DeleteTag removes a tag from the store index without deleting the underlying blobs.

func (*Store) GetBlob 

func (s *Store) GetBlob(ctx context.Context, d digest.Digest) ([]byte, error)

GetBlob retrieves a blob by digest.

func (*Store) GetIndex 

func (s *Store) GetIndex(ctx context.Context, d digest.Digest) (*ocispec.Index, error)

GetIndex retrieves and parses an image index by digest.

func (*Store) GetManifest 

func (s *Store) GetManifest(ctx context.Context, d digest.Digest) ([]byte, error)

GetManifest retrieves a manifest by digest.

func (*Store) IsIndex 

func (s *Store) IsIndex(ctx context.Context, d digest.Digest) (bool, error)

IsIndex checks if the content at the given digest is an image index.

func (*Store) ListTags 

func (s *Store) ListTags(ctx context.Context) ([]string, error)

ListTags returns all tags in the store.

func (*Store) PutBlob 

func (s *Store) PutBlob(ctx context.Context, content []byte) (digest.Digest, error)

PutBlob stores a blob and returns its digest.

func (*Store) PutManifest 

func (s *Store) PutManifest(ctx context.Context, content []byte) (digest.Digest, error)

PutManifest stores a manifest and returns its digest.

func (*Store) Resolve 

func (s *Store) Resolve(ctx context.Context, tag string) (digest.Digest, error)

Resolve resolves a tag to a manifest digest.

func (*Store) Root 

func (s *Store) Root() string

Root returns the store root directory.

func (*Store) Tag 

func (s *Store) Tag(ctx context.Context, d digest.Digest, tag string) error

Tag associates a tag with a manifest digest.

func (*Store) Target 

func (s *Store) Target() oras.Target

Target returns the underlying oras.Target for direct use by registry operations.

type TarOptions 

type TarOptions = artifact.TarOptions

TarOptions configures reproducible tar archive creation. Deprecated: use github.com/stacklok/toolhive-core/oci/artifact.TarOptions.

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.