skills

package
v0.4.4 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 39 Imported by: 0

Documentation

Overview

Package skills provides the core types and loading primitives for AgentSkills `SKILL.md` files.

Index

Constants

View Source
const (
	ExposureCodeSkillNotExposable        = "skill_not_exposable"
	ExposureCodeProfileSkillNotExposable = "profile_skill_not_exposable"
	ExposureCodeTargetDisabled           = "expose_target_disabled"
	ExposureCodeTargetInvalid            = "expose_target_invalid"
	ExposureCodeNameConflict             = "expose_name_conflict"
	ExposureCodeLinkUnsupported          = "expose_link_unsupported"
	ExposureCodeForeignLink              = "expose_foreign_link"
	ExposureCodeUnsafeSkillName          = "unsafe_skill_name"
	ExposureCodeRolledBack               = "rolled_back"
	ExposureCodeNotApplied               = "expose_not_applied"
	ExposureCodeCleanupFailed            = "exposure_cleanup_failed"
	ExposureCodeSkillRemoveBlocked       = "skill_remove_blocked"
)
View Source
const (

	// ManagedSkillLoadingInstructions keeps managed skill loading on canonical native tools.
	ManagedSkillLoadingInstructions = "Do not invoke `compozy skill view` or read skill files directly from a managed session. " +
		"If current tool policy denies canonical `compozy__skill_view`, report that the skill cannot be loaded; `compozy skill view` is an operator-shell command only."
)
View Source
const (

	// SkillFailureCodeDefinitionInvalid identifies a SKILL.md definition that could not be parsed.
	SkillFailureCodeDefinitionInvalid = "definition_invalid"
)
View Source
const (
	// SkillResourceKind is the canonical desired-state resource kind for skill definitions.
	SkillResourceKind resources.ResourceKind = "skill"
)

Variables

View Source
var (
	// ErrAgentNotFound reports that the requested agent is unavailable in the selected scope.
	ErrAgentNotFound = errors.New("skills: agent not found")
	// ErrAgentLocalInvalid reports an invalid AGENT.md or agent-local skills layer.
	ErrAgentLocalInvalid = errors.New("skills: invalid agent-local layer")
)
View Source
var (
	// ErrResourcePathRequired reports a missing skill resource path.
	ErrResourcePathRequired = errors.New("skills: skill resource path is required")
	// ErrResourcePathRelative reports an absolute or platform-specific skill resource path.
	ErrResourcePathRelative = errors.New("skills: skill resource path must be relative")
	// ErrResourcePathOutside reports a skill resource path that escapes its skill directory.
	ErrResourcePathOutside = errors.New("skills: skill resource path must stay within the skill directory")
)
View Source
var ErrConfigGenerationSuperseded = errors.New("skills: config generation superseded")
View Source
var (
	// ErrInvalidDefinition reports malformed or incomplete SKILL.md metadata.
	ErrInvalidDefinition = errors.New("skills: invalid definition")
)
View Source
var ErrSymlinkEscape = errors.New("skills: symlink escapes skill directory")

ErrSymlinkEscape reports a skill payload symlink that resolves outside the skill directory.

Functions

func BuildCatalog

func BuildCatalog(skills []*Skill) string

BuildCatalog renders the XML-like available-skills block injected into agent system prompts.

func BuildCatalogWithinBudget

func BuildCatalogWithinBudget(skills []*Skill, maxRunes int) string

BuildCatalogWithinBudget renders a complete catalog within maxRunes by shortening descriptions. It returns an empty string when every identity cannot fit without cutting the catalog structure.

func BuildCurrentCatalog

func BuildCurrentCatalog(skills []*Skill) string

BuildCurrentCatalog renders the authoritative per-turn skills block injected ahead of live prompts.

func BuildCurrentCatalogUnchanged

func BuildCurrentCatalogUnchanged() string

BuildCurrentCatalogUnchanged renders the compact per-turn marker used when the catalog did not change.

func BuildCurrentCatalogWithinBudget

func BuildCurrentCatalogWithinBudget(skills []*Skill, maxRunes int) string

BuildCurrentCatalogWithinBudget renders the authoritative per-turn catalog without cutting tags or dropping individual skill identities.

func CommandSourceForSkill

func CommandSourceForSkill(skill *Skill) commandpkg.Source

CommandSourceForSkill returns the opaque exact-source identity used by slash command refs. A root-scoped skill is keyed by its physical root alone: registry reloads that leave the root in place must not invalidate an invocation admitted before them (issue #815).

func ComputeDirectoryHash

func ComputeDirectoryHash(skillDir string) (string, error)

ComputeDirectoryHash returns a deterministic SHA-256 digest for a skill directory payload, excluding the provenance sidecar itself.

func ComputeHash

func ComputeHash(content []byte) string

ComputeHash returns the SHA-256 hex digest for raw SKILL.md content bytes.

func ConfigGenerationFromContext

func ConfigGenerationFromContext(ctx context.Context) int64

ConfigGenerationFromContext returns the generation bound to registry publication work.

func HasSidecar

func HasSidecar(skillDir string) (bool, error)

HasSidecar reports whether a skill directory contains marketplace provenance metadata.

func NewResourceCodec

func NewResourceCodec() (resources.KindCodec[SkillResourceSpec], error)

NewResourceCodec builds the canonical skill resource codec.

func ReadSkillContent

func ReadSkillContent(path string) (string, error)

ReadSkillContent reads and returns the markdown body from a SKILL.md file.

func ReadSkillResourceContent

func ReadSkillResourceContent(skillDir string, relativePath string) (string, error)

ReadSkillResourceContent reads a resource file relative to a filesystem-backed skill directory.

func SkillMCPAllowed

func SkillMCPAllowed(skill *Skill) bool

SkillMCPAllowed restricts embedded MCP declarations to supported local skill sources.

func SkillPrecedenceRank

func SkillPrecedenceRank(source SkillSource) int

SkillPrecedenceRank returns an explicit low-to-high resolver rank.

func SkillPrecedenceTierName

func SkillPrecedenceTierName(source SkillSource) string

SkillPrecedenceTierName returns the canonical public resolver tier label.

func SkillSourceName

func SkillSourceName(source SkillSource) string

SkillSourceName returns the canonical string label for a skill source.

func VerifyHash

func VerifyHash(skillDir string, provenance *Provenance) error

VerifyHash recomputes the installed skill payload hash for a skill directory and compares it with the stored provenance hash.

func WithConfigGeneration

func WithConfigGeneration(ctx context.Context, generation int64) context.Context

WithConfigGeneration binds registry publication work to one settings generation.

func WithSourceEventCorrelation

func WithSourceEventCorrelation(ctx context.Context, correlation SourceEventCorrelation) context.Context

WithSourceEventCorrelation binds source lifecycle work to its owning profile, workspace, and actor.

func WriteSidecar

func WriteSidecar(skillDir string, provenance Provenance) error

WriteSidecar writes marketplace provenance metadata alongside a skill's SKILL.md file.

Types

type ActivationContext

type ActivationContext struct {
	Platform     string
	Environments []string
	Tools        []string
	Capabilities []string
}

ActivationContext is the authoritative runtime input used to evaluate activation gates.

type ActivationContextProvider

type ActivationContextProvider func(context.Context, ActivationTarget) (ActivationContext, error)

ActivationContextProvider resolves dynamic offer-time inputs for one catalog projection.

type ActivationGate

type ActivationGate string

ActivationGate identifies one supported metadata.compozy.when family.

const (
	ActivationGatePlatforms            ActivationGate = "platforms"
	ActivationGateEnvironments         ActivationGate = "environments"
	ActivationGateRequiresTools        ActivationGate = "requires_tools"
	ActivationGateRequiresCapabilities ActivationGate = "requires_capabilities"
)

type ActivationGates

type ActivationGates struct {
	Platforms            []string `json:"platforms,omitempty"             yaml:"platforms,omitempty"`
	Environments         []string `json:"environments,omitempty"          yaml:"environments,omitempty"`
	RequiresTools        []string `json:"requires_tools,omitempty"        yaml:"requires_tools,omitempty"`
	RequiresCapabilities []string `json:"requires_capabilities,omitempty" yaml:"requires_capabilities,omitempty"`
}

ActivationGates declares offer-time constraints from metadata.compozy.when.

type ActivationReason

type ActivationReason struct {
	Gate    ActivationGate
	Code    ActivationReasonCode
	Missing []string
	Message string
}

ActivationReason is one deterministic unmet activation gate.

type ActivationReasonCode

type ActivationReasonCode string

ActivationReasonCode identifies why an enabled skill is not currently offered.

const (
	ActivationReasonPlatformMismatch              ActivationReasonCode = "platform_mismatch"
	ActivationReasonEnvironmentContextUnavailable ActivationReasonCode = "environment_context_unavailable"
	ActivationReasonEnvironmentMismatch           ActivationReasonCode = "environment_mismatch"
	ActivationReasonToolContextUnavailable        ActivationReasonCode = "tool_context_unavailable"
	ActivationReasonMissingTool                   ActivationReasonCode = "missing_tool"
	ActivationReasonCapabilityContextUnavailable  ActivationReasonCode = "capability_context_unavailable"
	ActivationReasonMissingCapability             ActivationReasonCode = "missing_capability"
)

type ActivationTarget

type ActivationTarget struct {
	ProfileID         string
	WorkspaceID       string
	SessionID         string
	AgentName         string
	Capabilities      []string
	NeedsPlatform     bool
	NeedsEnvironments bool
	NeedsTools        bool
}

ActivationTarget identifies the runtime scope whose skill catalog is being projected.

type CatalogProvider

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

CatalogProvider builds the workspace-scoped skill catalog section expected by the composed prompt assembly pipeline.

func NewBoundedCatalogProvider

func NewBoundedCatalogProvider(registry *Registry, maxRunes int) *CatalogProvider

NewBoundedCatalogProvider constructs a CatalogProvider that keeps every advertised skill identity while fitting the rendered catalog within maxRunes.

func NewCatalogProvider

func NewCatalogProvider(registry *Registry) *CatalogProvider

NewCatalogProvider constructs a CatalogProvider backed by the provided registry.

func (*CatalogProvider) PromptAgentSection

func (cp *CatalogProvider) PromptAgentSection(
	ctx context.Context,
	agent compozyconfig.AgentDef,
	workspace *workspacepkg.ResolvedWorkspace,
) (string, error)

PromptStartupSection resolves the effective catalog for the concrete agent being started when the prompt assembler provides that identity.

func (*CatalogProvider) PromptAgentSessionFilteredSection

func (cp *CatalogProvider) PromptAgentSessionFilteredSection(
	ctx context.Context,
	sessionID string,
	agent compozyconfig.AgentDef,
	workspace *workspacepkg.ResolvedWorkspace,
	filter func(*Skill) bool,
) (string, error)

PromptAgentSessionFilteredSection applies one session-resolved injection-only filter.

func (*CatalogProvider) PromptAgentSessionSection

func (cp *CatalogProvider) PromptAgentSessionSection(
	ctx context.Context,
	sessionID string,
	agent compozyconfig.AgentDef,
	workspace *workspacepkg.ResolvedWorkspace,
) (string, error)

PromptAgentSessionSection resolves activation gates against the concrete startup session.

func (*CatalogProvider) PromptSection

func (cp *CatalogProvider) PromptSection(
	ctx context.Context,
	workspace *workspacepkg.ResolvedWorkspace,
) (string, error)

PromptSection loads the workspace-scoped skills and returns their XML-like catalog representation.

type CommandCandidate

type CommandCandidate struct {
	Skill      *Skill
	SourceKind string
	SourceID   string
	SourceKey  string
	Scope      string
	Qualified  bool
	Available  bool
	Origin     string
	RootID     string
}

CommandCandidate is one exact skill definition projected for slash discovery.

type ExposeManager

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

ExposeManager owns skill-link lifecycle for one exact configured root projection.

func NewExposeManager

func NewExposeManager(
	repository store.SkillExposureRepository,
	roots []compozyconfig.SkillRootSpec,
	options ...ExposeManagerOption,
) *ExposeManager

NewExposeManager constructs a manager scoped to one effective source projection.

func (*ExposeManager) CleanupCanonicalDir

func (m *ExposeManager) CleanupCanonicalDir(ctx context.Context, canonicalDir string) error

CleanupCanonicalDir removes every proven exposure before a canonical skill directory is deleted.

func (*ExposeManager) Expose

func (m *ExposeManager) Expose(
	ctx context.Context,
	skill *Skill,
	targets []string,
) ([]TargetResult, error)

Expose creates provider-root links after every requested target passes preflight.

func (*ExposeManager) Exposures

func (m *ExposeManager) Exposures(ctx context.Context, skill *Skill) ([]ExposureState, error)

Exposures returns durable records reconciled against current filesystem state.

func (*ExposeManager) Reconcile

func (m *ExposeManager) Reconcile(ctx context.Context, skill *Skill) ([]ExposureState, error)

Reconcile is the retryable inspection contract used by lifecycle callers.

func (*ExposeManager) Unexpose

func (m *ExposeManager) Unexpose(
	ctx context.Context,
	skill *Skill,
	targets []string,
) ([]TargetResult, error)

Unexpose removes only links proven by durable ownership records.

func (*ExposeManager) VerifyCanonicalDir

func (m *ExposeManager) VerifyCanonicalDir(ctx context.Context, canonicalDir string) error

VerifyCanonicalDir ensures every persisted exposure remains healthy after an in-place update.

type ExposeManagerOption

type ExposeManagerOption func(*ExposeManager)

ExposeManagerOption customizes exposure I/O and observability.

func WithExposureEventStore

func WithExposureEventStore(events store.EventSummaryStore) ExposeManagerOption

WithExposureEventStore records canonical exposure lifecycle events.

func WithExposureLogger

func WithExposureLogger(logger *slog.Logger) ExposeManagerOption

WithExposureLogger sets the logger used for best-effort event write failures.

type ExposureBatchError

type ExposureBatchError struct {
	RolledBack bool
	Cause      error
}

ExposureBatchError reports whether an expose operation compensated completed targets.

func (*ExposureBatchError) Error

func (e *ExposureBatchError) Error() string

func (*ExposureBatchError) Unwrap

func (e *ExposureBatchError) Unwrap() error

type ExposureError

type ExposureError struct {
	Code      string
	Target    string
	Path      string
	Message   string
	Retryable bool
	Cause     error
}

ExposureError carries one deterministic public error code.

func (*ExposureError) Error

func (e *ExposureError) Error() string

func (*ExposureError) Unwrap

func (e *ExposureError) Unwrap() error

type ExposureRecord

type ExposureRecord = store.SkillExposureRecord

ExposureRecord is the durable ownership proof for one link.

type ExposureState

type ExposureState struct {
	Record ExposureRecord
	Status ExposureStatus
}

ExposureState combines durable ownership with live filesystem health.

type ExposureStatus

type ExposureStatus string

ExposureStatus reports filesystem health relative to a durable ownership record.

const (
	ExposureHealthy         ExposureStatus = "healthy"
	ExposureMissing         ExposureStatus = "missing"
	ExposureBroken          ExposureStatus = "broken"
	ExposureForeignConflict ExposureStatus = "foreign_conflict"
)

type HashMismatchError

type HashMismatchError struct {
	ExpectedHash string
	ActualHash   string
}

HashMismatchError reports a provenance hash mismatch for a marketplace skill.

func (*HashMismatchError) Error

func (e *HashMismatchError) Error() string

Error implements the error interface.

type MCPResolver

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

MCPResolver collects and resolves MCP server declarations from enabled skills.

func NewMCPResolver

func NewMCPResolver(logger *slog.Logger) *MCPResolver

NewMCPResolver constructs an MCPResolver with logger settings.

func (*MCPResolver) Resolve

func (mr *MCPResolver) Resolve(skills []*Skill) []compozyconfig.MCPServer

Resolve returns MCP servers from enabled skills after trust-tier filtering. When multiple declarations share the same trimmed server name, the later skill in source-precedence order replaces the earlier one ("last wins"). The caller then passes the result through compozyconfig.MergeMCPServers, which keeps the first server at each final position. Combined together, skill-local duplicates are resolved last-wins before config-vs-skill merge applies its first-wins behavior.

type MCPServerDecl

type MCPServerDecl struct {
	Name      string            `yaml:"name"`
	Command   string            `yaml:"command"`
	Args      []string          `yaml:"args,omitempty"`
	Env       map[string]string `yaml:"env,omitempty"`
	SecretEnv map[string]string `yaml:"secret_env,omitempty"`
}

MCPServerDecl declares an MCP server dependency in skill frontmatter.

type Option

type Option func(*Registry)

Option customizes a Registry instance.

func WithActivationContextProvider

func WithActivationContextProvider(provider ActivationContextProvider) Option

WithActivationContextProvider injects late-bound runtime activation inputs.

func WithEventSummaryStore

func WithEventSummaryStore(events store.EventSummaryStore) Option

WithEventSummaryStore injects the optional global observe-event writer used for public skill.shadowed and skills.load_failed events.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger injects the logger used for registry diagnostics.

func WithNow

func WithNow(now func() time.Time) Option

WithNow injects the clock used for cache timestamps and eviction.

type Provenance

type Provenance struct {
	Hash        string    `json:"hash"`
	Registry    string    `json:"registry"`
	Slug        string    `json:"slug"`
	Version     string    `json:"version"`
	InstalledAt time.Time `json:"installed_at"`
}

Provenance stores marketplace install metadata for a skill.

func ReadSidecar

func ReadSidecar(skillDir string) (*Provenance, error)

ReadSidecar reads marketplace provenance metadata from a skill directory.

type Registry

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

Registry manages global skills loaded at boot and lazily cached workspace skills.

func NewRegistry

func NewRegistry(cfg RegistryConfig, opts ...Option) *Registry

NewRegistry constructs a Registry with the provided configuration.

func (*Registry) AbortConfigGeneration

func (r *Registry) AbortConfigGeneration(generation int64)

AbortConfigGeneration discards an uncommitted candidate without touching the active catalog.

func (*Registry) ApplyConfigGeneration

func (r *Registry) ApplyConfigGeneration(
	ctx context.Context,
	generation int64,
	cfg RegistryConfig,
) (bool, error)

ApplyConfigGeneration stages a new source policy and commits it directly when resources are not authoritative. A true result requires the caller to republish skill resources using the same generation-bound context.

func (*Registry) ApplyResourceRecords

func (r *Registry) ApplyResourceRecords(
	ctx context.Context,
	revision int64,
	records []resources.Record[SkillResourceSpec],
) error

ApplyResourceRecords atomically replaces the runtime skill catalog with the canonical resource projection.

func (*Registry) CommandCandidatesForAgentDefSession

func (r *Registry) CommandCandidatesForAgentDefSession(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agent compozyconfig.AgentDef,
	sessionID string,
) ([]CommandCandidate, error)

CommandCandidatesForAgentDefSession returns bare effective skills plus every source-qualified external skill visible to one session.

func (*Registry) CommandCandidatesForAgentSession

func (r *Registry) CommandCandidatesForAgentSession(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agentName string,
	sessionID string,
) ([]CommandCandidate, error)

CommandCandidatesForAgentSession resolves one named session agent before projecting its slash-command candidates.

func (*Registry) CommitConfigGeneration

func (r *Registry) CommitConfigGeneration(ctx context.Context, generation int64) error

CommitConfigGeneration atomically publishes a staged resource projection and its source policy.

func (*Registry) ConfigGeneration

func (r *Registry) ConfigGeneration() int64

ConfigGeneration returns the last source-policy generation committed with the catalog.

func (*Registry) DiscoverGlobal

func (r *Registry) DiscoverGlobal(ctx context.Context) ([]*Skill, map[string]filesnap.Snapshot, error)

DiscoverGlobal loads global skill definitions for resource publication without making the file-system scan authoritative in the registry.

func (*Registry) DiscoverWorkspace

func (r *Registry) DiscoverWorkspace(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
) ([]*Skill, map[string]filesnap.Snapshot, error)

DiscoverWorkspace loads workspace-visible skill definitions for resource publication.

func (*Registry) EmitSourceApplyFailed

func (r *Registry) EmitSourceApplyFailed(
	ctx context.Context,
	generation int64,
	err error,
) error

EmitSourceApplyFailed records a source apply failure after the active catalog has been preserved.

func (*Registry) ExposureRoots

func (r *Registry) ExposureRoots(resolved *workspacepkg.ResolvedWorkspace) []compozyconfig.SkillRootSpec

ExposureRoots returns the active roots that can participate in exposure for one catalog scope.

func (*Registry) ForAgent

func (r *Registry) ForAgent(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agentName string,
) ([]*Skill, error)

ForAgent returns the effective skill set for one logical agent after applying the final agent-local overlay over the current global/workspace-effective set.

func (*Registry) ForAgentDef

func (r *Registry) ForAgentDef(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agent compozyconfig.AgentDef,
) ([]*Skill, error)

ForAgentDef returns the effective skill set for an already-resolved concrete agent definition.

func (*Registry) ForAgentDefSession

func (r *Registry) ForAgentDefSession(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agent compozyconfig.AgentDef,
	sessionID string,
) ([]*Skill, error)

ForAgentDefSession projects offer-time skill activation from the concrete definition that owns the session, including extension and bundle agents that are not authored on disk.

func (*Registry) ForAgentSession

func (r *Registry) ForAgentSession(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agentName string,
	sessionID string,
) ([]*Skill, error)

ForAgentSession returns the effective offer-time skill projection for one session.

func (*Registry) ForProfile

func (r *Registry) ForProfile(ctx context.Context, profileName string, profileRoot string) ([]*Skill, error)

ForProfile returns the global skill set overlaid with one personal profile's skills.

func (*Registry) ForWorkspace

func (r *Registry) ForWorkspace(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace) ([]*Skill, error)

ForWorkspace returns the global skill set overlaid with resolver-provided workspace skills.

func (*Registry) Get

func (r *Registry) Get(name string) (*Skill, bool)

Get returns a cloned global skill by name when present.

func (*Registry) GlobalVersion

func (r *Registry) GlobalVersion() int64

GlobalVersion returns the current global snapshot version.

func (*Registry) List

func (r *Registry) List() []*Skill

List returns the current global skills sorted by skill name.

func (*Registry) LoadAll

func (r *Registry) LoadAll(ctx context.Context) error

LoadAll loads bundled and user-level skills into the global registry snapshot.

func (*Registry) LoadContent

func (r *Registry) LoadContent(ctx context.Context, skill *Skill) (string, error)

LoadContent loads the full markdown body for one resolved skill.

func (*Registry) LoadResource

func (r *Registry) LoadResource(ctx context.Context, skill *Skill, relativePath string) (string, error)

LoadResource loads a resource file relative to one resolved skill.

func (*Registry) RefreshGlobal

func (r *Registry) RefreshGlobal(ctx context.Context) error

RefreshGlobal re-scans the global skill sources and swaps them in atomically.

func (*Registry) SetEnabled

func (r *Registry) SetEnabled(name string, resolved *workspacepkg.ResolvedWorkspace, enabled bool) error

SetEnabled updates the runtime enabled state for a named skill and keeps the disabled-skills overlay in sync so future reloads preserve the change.

func (*Registry) SetEnabledForAgent

func (r *Registry) SetEnabledForAgent(
	name string,
	resolved *workspacepkg.ResolvedWorkspace,
	agentName string,
	enabled bool,
) error

SetEnabledForAgent persists an agent-scoped logical tombstone in the winning AGENT.md.

func (*Registry) SetEventSummaryStore

func (r *Registry) SetEventSummaryStore(events store.EventSummaryStore)

SetEventSummaryStore updates the optional global observe-event writer after registry construction.

func (*Registry) SkillDiagnostics

func (r *Registry) SkillDiagnostics(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
	agentName string,
) ([]SkillDiagnostic, error)

SkillDiagnostics returns diagnostics for the same resolution scope used by List, ForWorkspace, and ForAgent. It does not change resolution semantics.

func (*Registry) SkillSourceRoots

func (r *Registry) SkillSourceRoots(
	ctx context.Context,
	resolved *workspacepkg.ResolvedWorkspace,
) ([]SkillSourceRootStatus, error)

SkillSourceRoots returns the exact projection roots and their current measurements.

func (*Registry) SourceApplyFailureError

func (r *Registry) SourceApplyFailureError(ctx context.Context, generation int64, cause error) error

SourceApplyFailureError adds the canonical failure event without obscuring the original cause.

type RegistryConfig

type RegistryConfig struct {
	BundledFS        fs.FS
	GlobalSkillRoots []compozyconfig.SkillRootSpec
	GlobalAgentsDir  string
	DisabledSkills   []string
}

RegistryConfig controls how the registry discovers global skills.

type ShadowEntry

type ShadowEntry struct {
	Path             string
	Tier             string
	Origin           string
	ResolvedToWinner bool
	DetectedAt       time.Time
}

ShadowEntry is the public read model for one declaration participating in skill resolution. The winner and every shadowed declaration come from the same resolver snapshot.

type Skill

type Skill struct {
	Meta                   SkillMeta
	Source                 SkillSource
	Dir                    string
	FilePath               string
	Enabled                bool
	ActivationGates        ActivationGates
	Activation             SkillActivation
	MCPServers             []MCPServerDecl
	Hooks                  []hookspkg.HookDecl
	Provenance             *Provenance
	InstalledFrom          string
	InstalledFromExtension string
	CommandScope           string
	Origin                 string
	RootID                 string
	RootDir                string
	ResourceScope          resources.ResourceScope
	Diagnostics            SkillDiagnostics
}

Skill is the metadata-first in-memory representation of a parsed skill file.

func ParseSkillFile

func ParseSkillFile(path string) (*Skill, error)

ParseSkillFile reads and parses a SKILL.md file from disk.

The loader fills parsed metadata plus canonical file locations. The skill body is intentionally not retained on the returned Skill; callers must use ReadSkillContent when they need the full instructions.

func ParseSkillFileWithSource

func ParseSkillFileWithSource(path string, source SkillSource) (*Skill, error)

ParseSkillFileWithSource reads and parses a skill file from disk while preserving the caller-selected source tier for downstream precedence and hook metadata handling.

func SkillFromResourceSpec

func SkillFromResourceSpec(spec SkillResourceSpec) (*Skill, error)

SkillFromResourceSpec converts a canonical resource spec into the runtime skill shape.

type SkillActivation

type SkillActivation struct {
	Active    bool
	Evaluated bool
	Reasons   []ActivationReason
}

SkillActivation is the latest offer-time evaluation for one resolved skill.

type SkillDefinitionRef

type SkillDefinitionRef struct {
	Source     string
	Origin     string
	Path       string
	DetectedAt time.Time
}

SkillDefinitionRef identifies a skill definition involved in resolution diagnostics.

type SkillDiagnostic

type SkillDiagnostic struct {
	Name               string
	State              SkillDiagnosticState
	Source             string
	Path               string
	WinningSource      string
	WinningPath        string
	VerificationStatus SkillVerificationStatus
	Warnings           []Warning
	Failure            *SkillVerificationFailure
	ActivationReasons  []ActivationReason
}

SkillDiagnostic is the public read model for one effective, shadowed, or rejected definition.

func DiagnosticsForSkill

func DiagnosticsForSkill(skill *Skill) []SkillDiagnostic

DiagnosticsForSkill returns the diagnostics visible for one effective skill.

type SkillDiagnosticState

type SkillDiagnosticState string

SkillDiagnosticState describes how one discovered skill definition resolved.

const (
	// SkillDiagnosticStateValid reports a loaded definition that participates in the effective skill set.
	SkillDiagnosticStateValid SkillDiagnosticState = "valid"
	// SkillDiagnosticStateShadowed reports a definition superseded by a higher-precedence definition.
	SkillDiagnosticStateShadowed SkillDiagnosticState = "shadowed"
	// SkillDiagnosticStateVerificationFailed reports a definition rejected by provenance or content verification.
	SkillDiagnosticStateVerificationFailed SkillDiagnosticState = "verification_failed"
	// SkillDiagnosticStateInactive reports a valid enabled definition withheld by activation gates.
	SkillDiagnosticStateInactive SkillDiagnosticState = "inactive"
)

type SkillDiagnostics

type SkillDiagnostics struct {
	VerificationStatus  SkillVerificationStatus
	Warnings            []Warning
	ShadowedDefinitions []SkillDefinitionRef
}

SkillDiagnostics stores verifier and resolution diagnostics on an effective skill.

type SkillMeta

type SkillMeta struct {
	Name        string         `yaml:"name"`
	Description string         `yaml:"description"`
	Version     string         `yaml:"version,omitempty"`
	Metadata    map[string]any `yaml:"metadata,omitempty"`
}

SkillMeta maps YAML frontmatter fields per the AgentSkills spec.

type SkillResourceSpec

type SkillResourceSpec struct {
	Name                   string              `json:"name"`
	Description            string              `json:"description"`
	Version                string              `json:"version,omitempty"`
	Metadata               map[string]any      `json:"metadata,omitempty"`
	Source                 string              `json:"source"`
	Dir                    string              `json:"dir,omitempty"`
	FilePath               string              `json:"file_path,omitempty"`
	Enabled                bool                `json:"enabled"`
	ActivationGates        ActivationGates     `json:"activation_gates,omitzero"`
	MCPServers             []MCPServerDecl     `json:"mcp_servers,omitempty"`
	Hooks                  []hookspkg.HookDecl `json:"hooks,omitempty"`
	Provenance             *Provenance         `json:"provenance,omitzero"`
	InstalledFrom          string              `json:"installed_from,omitempty"`
	InstalledFromExtension string              `json:"installed_from_extension,omitempty"`
	Origin                 string              `json:"origin,omitempty"`
	RootID                 string              `json:"root_id,omitempty"`
	RootDir                string              `json:"root_dir,omitempty"`
}

SkillResourceSpec is the resource-backed metadata index for one parsed skill.

The full SKILL.md body intentionally remains outside the resource record and is loaded through the skills package when callers need content.

func SkillToResourceSpec

func SkillToResourceSpec(skill *Skill) SkillResourceSpec

SkillToResourceSpec converts a parsed skill into its canonical resource spec.

type SkillShadows

type SkillShadows struct {
	Name    string
	Winner  ShadowEntry
	Shadows []ShadowEntry
}

SkillShadows describes every declaration for one skill name with the resolver winner called out explicitly.

func ShadowsForSkill

func ShadowsForSkill(skill *Skill, fallbackDetectedAt time.Time) (SkillShadows, bool)

ShadowsForSkill returns the resolver winner and every known shadowed definition for one effective skill. It does not perform resolution itself.

func ShadowsForSkillList

func ShadowsForSkillList(skills []*Skill, name string, fallbackDetectedAt time.Time) (SkillShadows, bool)

ShadowsForSkillList returns shadow evidence for a named winner in a resolved skill list.

type SkillSource

type SkillSource int

SkillSource identifies where a skill was loaded from.

const (
	// SourceBundled is the lowest-precedence source backed by go:embed files.
	SourceBundled SkillSource = iota
	// SourceMarketplace identifies skills installed from a marketplace registry.
	SourceMarketplace
	// SourceUser identifies skills loaded from the user-level skill directories.
	SourceUser
	// SourceProfile identifies personal skills under the active profile directory.
	SourceProfile
	// SourceAdditional identifies skills loaded from additional workspace roots.
	SourceAdditional
	// SourceWorkspace is the highest-precedence source from `<workspace>/.compozy/skills/`.
	SourceWorkspace
	// SourceWorkspaceProfile identifies project skills bound to the active profile name.
	SourceWorkspaceProfile
	// SourceAgentLocal is the final overlay from `<root>/.compozy/agents/<name>/skills/`.
	SourceAgentLocal
)

type SkillSourceCollision

type SkillSourceCollision struct {
	Name          string
	WinnerRootID  string
	QualifiedForm string
}

SkillSourceCollision reports one name shadow resolved across source roots.

type SkillSourceRootStatus

type SkillSourceRootStatus struct {
	Spec          compozyconfig.SkillRootSpec
	Exists        bool
	Readable      bool
	ScannedCount  int
	SkillCount    int
	Truncated     bool
	SkippedLinks  []skillscan.SkippedLink
	Collisions    []SkillSourceCollision
	Verification  SkillSourceVerification
	NativeReaders []string
}

SkillSourceRootStatus is the daemon-owned measurement for one configured root.

type SkillSourceSkippedLink = skillscan.SkippedLink

SkillSourceSkippedLink explains why a first-level directory link was excluded.

type SkillSourceVerification

type SkillSourceVerification struct {
	Blocked int
	Warned  int
}

SkillSourceVerification summarizes verifier outcomes for one root.

type SkillVerificationFailure

type SkillVerificationFailure struct {
	Code         string
	Message      string
	ExpectedHash string
	ActualHash   string
}

SkillVerificationFailure captures an actionable verification rejection.

type SkillVerificationStatus

type SkillVerificationStatus string

SkillVerificationStatus describes the verifier outcome for one skill definition.

const (
	// SkillVerificationStatusPassed means no verifier warning or error is attached.
	SkillVerificationStatusPassed SkillVerificationStatus = "passed"
	// SkillVerificationStatusWarning means non-blocking verifier warnings were found.
	SkillVerificationStatusWarning SkillVerificationStatus = "warning"
	// SkillVerificationStatusFailed means the definition was rejected by verification.
	SkillVerificationStatusFailed SkillVerificationStatus = "failed"
)

type SourceEventCorrelation

type SourceEventCorrelation struct {
	Scope       string
	ProfileID   string
	WorkspaceID string
	ActorKind   string
	ActorID     string
	RootCounts  map[string]int
}

SourceEventCorrelation identifies the exact owner and actor for source lifecycle events.

func SourceEventCorrelationFromContext

func SourceEventCorrelationFromContext(ctx context.Context) SourceEventCorrelation

SourceEventCorrelationFromContext returns the normalized source owner and actor bound to work.

type TargetResult

type TargetResult struct {
	Target     string
	OK         bool
	Exposure   *ExposureState
	Err        error
	RolledBack bool
	CleanupErr error
}

TargetResult reports one target's independent operation result.

type Warning

type Warning struct {
	Severity WarningSeverity
	Message  string
	Pattern  string
}

Warning captures a verification or loading concern associated with a skill.

func VerifyContent

func VerifyContent(content string) []Warning

VerifyContent scans skill content for prompt-injection and abuse patterns.

type WarningSeverity

type WarningSeverity int

WarningSeverity describes the impact of a loader or verifier warning.

const (
	SeverityInfo WarningSeverity = iota
	SeverityWarning
	SeverityCritical
)

type Watcher

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

Watcher polls global skill directories and refreshes the registry when their SKILL.md snapshots change.

func NewWatcher

func NewWatcher(registry *Registry, interval time.Duration) *Watcher

NewWatcher constructs a watcher that polls the registry's global skill directories. A non-positive interval falls back to the default poll interval.

func (*Watcher) SetAfterRefresh

func (w *Watcher) SetAfterRefresh(callback func(context.Context) error)

SetAfterRefresh installs an optional callback that runs after a successful registry refresh and before watcher snapshots are committed.

func (*Watcher) SetAgentRootsProvider

func (w *Watcher) SetAgentRootsProvider(provider func(context.Context) ([]string, error))

SetAgentRootsProvider installs the explicit agent-definition roots watched on each poll.

func (*Watcher) SetRootsProvider

func (w *Watcher) SetRootsProvider(provider func(context.Context) ([]string, error))

SetRootsProvider installs an optional callback that contributes additional directories to watch on each poll, such as workspace-local skill roots.

func (*Watcher) Start

func (w *Watcher) Start(ctx context.Context)

Start runs the polling loop until the provided context is canceled.

Jump to

Keyboard shortcuts

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