Documentation
¶
Overview ¶
Package skills provides the core types and loading primitives for AgentSkills `SKILL.md` files.
Index ¶
- Constants
- Variables
- func BuildCatalog(skills []*Skill) string
- func BuildCatalogWithinBudget(skills []*Skill, maxRunes int) string
- func BuildCurrentCatalog(skills []*Skill) string
- func BuildCurrentCatalogUnchanged() string
- func BuildCurrentCatalogWithinBudget(skills []*Skill, maxRunes int) string
- func CommandSourceForSkill(skill *Skill) commandpkg.Source
- func ComputeDirectoryHash(skillDir string) (string, error)
- func ComputeHash(content []byte) string
- func ConfigGenerationFromContext(ctx context.Context) int64
- func HasSidecar(skillDir string) (bool, error)
- func NewResourceCodec() (resources.KindCodec[SkillResourceSpec], error)
- func ReadSkillContent(path string) (string, error)
- func ReadSkillResourceContent(skillDir string, relativePath string) (string, error)
- func SkillMCPAllowed(skill *Skill) bool
- func SkillPrecedenceRank(source SkillSource) int
- func SkillPrecedenceTierName(source SkillSource) string
- func SkillSourceName(source SkillSource) string
- func VerifyHash(skillDir string, provenance *Provenance) error
- func WithConfigGeneration(ctx context.Context, generation int64) context.Context
- func WithSourceEventCorrelation(ctx context.Context, correlation SourceEventCorrelation) context.Context
- func WriteSidecar(skillDir string, provenance Provenance) error
- type ActivationContext
- type ActivationContextProvider
- type ActivationGate
- type ActivationGates
- type ActivationReason
- type ActivationReasonCode
- type ActivationTarget
- type CatalogProvider
- func (cp *CatalogProvider) PromptAgentSection(ctx context.Context, agent compozyconfig.AgentDef, ...) (string, error)
- func (cp *CatalogProvider) PromptAgentSessionFilteredSection(ctx context.Context, sessionID string, agent compozyconfig.AgentDef, ...) (string, error)
- func (cp *CatalogProvider) PromptAgentSessionSection(ctx context.Context, sessionID string, agent compozyconfig.AgentDef, ...) (string, error)
- func (cp *CatalogProvider) PromptSection(ctx context.Context, workspace *workspacepkg.ResolvedWorkspace) (string, error)
- type CommandCandidate
- type ExposeManager
- func (m *ExposeManager) CleanupCanonicalDir(ctx context.Context, canonicalDir string) error
- func (m *ExposeManager) Expose(ctx context.Context, skill *Skill, targets []string) ([]TargetResult, error)
- func (m *ExposeManager) Exposures(ctx context.Context, skill *Skill) ([]ExposureState, error)
- func (m *ExposeManager) Reconcile(ctx context.Context, skill *Skill) ([]ExposureState, error)
- func (m *ExposeManager) Unexpose(ctx context.Context, skill *Skill, targets []string) ([]TargetResult, error)
- func (m *ExposeManager) VerifyCanonicalDir(ctx context.Context, canonicalDir string) error
- type ExposeManagerOption
- type ExposureBatchError
- type ExposureError
- type ExposureRecord
- type ExposureState
- type ExposureStatus
- type HashMismatchError
- type MCPResolver
- type MCPServerDecl
- type Option
- type Provenance
- type Registry
- func (r *Registry) AbortConfigGeneration(generation int64)
- func (r *Registry) ApplyConfigGeneration(ctx context.Context, generation int64, cfg RegistryConfig) (bool, error)
- func (r *Registry) ApplyResourceRecords(ctx context.Context, revision int64, ...) error
- func (r *Registry) CommandCandidatesForAgentDefSession(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]CommandCandidate, error)
- func (r *Registry) CommandCandidatesForAgentSession(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]CommandCandidate, error)
- func (r *Registry) CommitConfigGeneration(ctx context.Context, generation int64) error
- func (r *Registry) ConfigGeneration() int64
- func (r *Registry) DiscoverGlobal(ctx context.Context) ([]*Skill, map[string]filesnap.Snapshot, error)
- func (r *Registry) DiscoverWorkspace(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace) ([]*Skill, map[string]filesnap.Snapshot, error)
- func (r *Registry) EmitSourceApplyFailed(ctx context.Context, generation int64, err error) error
- func (r *Registry) ExposureRoots(resolved *workspacepkg.ResolvedWorkspace) []compozyconfig.SkillRootSpec
- func (r *Registry) ForAgent(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]*Skill, error)
- func (r *Registry) ForAgentDef(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]*Skill, error)
- func (r *Registry) ForAgentDefSession(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]*Skill, error)
- func (r *Registry) ForAgentSession(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]*Skill, error)
- func (r *Registry) ForProfile(ctx context.Context, profileName string, profileRoot string) ([]*Skill, error)
- func (r *Registry) ForWorkspace(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace) ([]*Skill, error)
- func (r *Registry) Get(name string) (*Skill, bool)
- func (r *Registry) GlobalVersion() int64
- func (r *Registry) List() []*Skill
- func (r *Registry) LoadAll(ctx context.Context) error
- func (r *Registry) LoadContent(ctx context.Context, skill *Skill) (string, error)
- func (r *Registry) LoadResource(ctx context.Context, skill *Skill, relativePath string) (string, error)
- func (r *Registry) RefreshGlobal(ctx context.Context) error
- func (r *Registry) SetEnabled(name string, resolved *workspacepkg.ResolvedWorkspace, enabled bool) error
- func (r *Registry) SetEnabledForAgent(name string, resolved *workspacepkg.ResolvedWorkspace, agentName string, ...) error
- func (r *Registry) SetEventSummaryStore(events store.EventSummaryStore)
- func (r *Registry) SkillDiagnostics(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace, ...) ([]SkillDiagnostic, error)
- func (r *Registry) SkillSourceRoots(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace) ([]SkillSourceRootStatus, error)
- func (r *Registry) SourceApplyFailureError(ctx context.Context, generation int64, cause error) error
- type RegistryConfig
- type ShadowEntry
- type Skill
- type SkillActivation
- type SkillDefinitionRef
- type SkillDiagnostic
- type SkillDiagnosticState
- type SkillDiagnostics
- type SkillMeta
- type SkillResourceSpec
- type SkillShadows
- type SkillSource
- type SkillSourceCollision
- type SkillSourceRootStatus
- type SkillSourceSkippedLink
- type SkillSourceVerification
- type SkillVerificationFailure
- type SkillVerificationStatus
- type SourceEventCorrelation
- type TargetResult
- type Warning
- type WarningSeverity
- type Watcher
Constants ¶
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" )
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."
)
const (
// SkillFailureCodeDefinitionInvalid identifies a SKILL.md definition that could not be parsed.
SkillFailureCodeDefinitionInvalid = "definition_invalid"
)
const ( // SkillResourceKind is the canonical desired-state resource kind for skill definitions. SkillResourceKind resources.ResourceKind = "skill" )
Variables ¶
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") )
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") )
var ErrConfigGenerationSuperseded = errors.New("skills: config generation superseded")
var ( // ErrInvalidDefinition reports malformed or incomplete SKILL.md metadata. ErrInvalidDefinition = errors.New("skills: invalid definition") )
var ErrSymlinkEscape = errors.New("skills: symlink escapes skill directory")
ErrSymlinkEscape reports a skill payload symlink that resolves outside the skill directory.
Functions ¶
func BuildCatalog ¶
BuildCatalog renders the XML-like available-skills block injected into agent system prompts.
func BuildCatalogWithinBudget ¶
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 ¶
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 ¶
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.
func ComputeDirectoryHash ¶
ComputeDirectoryHash returns a deterministic SHA-256 digest for a skill directory payload, excluding the provenance sidecar itself.
func ComputeHash ¶
ComputeHash returns the SHA-256 hex digest for raw SKILL.md content bytes.
func ConfigGenerationFromContext ¶
ConfigGenerationFromContext returns the generation bound to registry publication work.
func HasSidecar ¶
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 ¶
ReadSkillContent reads and returns the markdown body from a SKILL.md file.
func ReadSkillResourceContent ¶
ReadSkillResourceContent reads a resource file relative to a filesystem-backed skill directory.
func SkillMCPAllowed ¶
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 ¶
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" ActivationReasonEnvironmentMismatch ActivationReasonCode = "environment_mismatch" ActivationReasonMissingTool ActivationReasonCode = "missing_tool" 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
Generation int64
}
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 ¶
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 ¶
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 ¶
WithLogger injects the logger used for registry diagnostics.
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 ¶
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 ¶
CommitConfigGeneration atomically publishes a staged resource projection and its source policy.
func (*Registry) ConfigGeneration ¶
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 ¶
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) GlobalVersion ¶
GlobalVersion returns the current global snapshot version.
func (*Registry) LoadAll ¶
LoadAll loads bundled and user-level skills into the global registry snapshot.
func (*Registry) LoadContent ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
type SkillSourceSkippedLink = skillscan.SkippedLink
SkillSourceSkippedLink explains why a first-level directory link was excluded.
type SkillSourceVerification ¶
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 ¶
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 ¶
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 ¶
SetAfterRefresh installs an optional callback that runs after a successful registry refresh and before watcher snapshots are committed.
func (*Watcher) SetAgentRootsProvider ¶
SetAgentRootsProvider installs the explicit agent-definition roots watched on each poll.
func (*Watcher) SetRootsProvider ¶
SetRootsProvider installs an optional callback that contributes additional directories to watch on each poll, such as workspace-local skill roots.
Source Files
¶
- activation.go
- catalog.go
- diagnostics.go
- expose_cleanup.go
- expose_events.go
- expose_lifecycle.go
- expose_manager.go
- expose_operation.go
- expose_path.go
- expose_reconcile.go
- expose_types.go
- expose_unexpose.go
- hook_decl.go
- loader.go
- loader_declarations.go
- loader_values.go
- mcp.go
- mcp_sidecar.go
- metadata.go
- observe_events.go
- path_security.go
- provenance.go
- registry.go
- registry_agent.go
- registry_command.go
- registry_config_generation.go
- registry_diagnostics.go
- registry_disabled.go
- registry_discovery.go
- registry_exposure_roots.go
- registry_load.go
- registry_override_log.go
- registry_reserved_runtime.go
- registry_resource_projection.go
- registry_snapshot.go
- registry_source.go
- registry_toggle.go
- registry_workspace_cache.go
- registry_workspace_projection.go
- resource.go
- resource_spec.go
- shadows.go
- source_events.go
- source_status.go
- types.go
- verify.go
- watcher.go