Help us shape the future of Go! Take the 2026 Go Developer Survey

skills

package
v0.13.21 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
const (
	PresetEpicPlanner        = "epic_planner"
	PresetTaskPlanner        = "task_planner"
	PresetCRMOperator        = "crm_operator"
	PresetSupportAgent       = "support_agent"
	PresetDocumentationAgent = "documentation_agent"
	PresetCodeBuilder        = "code_builder"
	PresetReviewAgent        = "review_agent"
	PresetCommandAgent       = "researcher"

	PlanningStageDraftSpec   = "draft_spec"
	PlanningStagePlanTasks   = "plan_tasks"
	PlanningStageTaskPlanDoc = "task_plan_doc"
)
View Source
const (
	SourceBuiltIn    = "built_in"
	SourceWorkspace  = "workspace"
	SourceImported   = "imported"
	SourceConfigured = "configured"

	InteractionKindRequestUserInput = "request_user_input"
	InteractionKindApprovalRequest  = "approval_request"
	InteractionKindReviewCheckpoint = "review_checkpoint"

	TransportTypeToolCall      = "tool_call"
	TransportTypeFencedJSON    = "fenced_json"
	TransportTypeRuntimeBridge = "runtime_bridge"

	RuntimeSkillRoleConfigKey   = "runtime_skill_role"
	RuntimeSkillRoleInstruction = "instruction"
	RuntimeSkillRoleAvailable   = "available"
)
View Source
const BuiltInRoot = "system"
View Source
const SourceRepository = "repository"

SourceRepository marks skills discovered inside the run's repository checkout. They are available skills only: never active, no policy, no required tools. They carry the same trust as the repository's AGENTS.md.

Variables

View Source
var BuiltInFS embed.FS

Functions

func BuildSkillArchive

func BuildSkillArchive(def Definition) ([]byte, string, string, error)

func CompileInstructionModules

func CompileInstructionModules(definitions []Definition, moduleKeys []string) string

func CompileInstructions

func CompileInstructions(definitions []Definition) string

func CompilePresetInstructions

func CompilePresetInstructions(definitions []Definition, preamble string, moduleKeys []string) string

func CompletionRequiredInteractionKinds

func CompletionRequiredInteractionKinds(policy Policy, definitions []Definition) []string

CompletionRequiredInteractionKinds returns the interaction kinds that must exist before a run may complete. Required interaction tools are treated as a fallback contract so a partial workspace-skill response cannot silently discard approval or input requirements carried by the skill package.

func CopyBuiltInSkillPackageToDir

func CopyBuiltInSkillPackageToDir(key, destDir string) error

func EmbeddedBuiltInPresetInstructionTemplateVersion

func EmbeddedBuiltInPresetInstructionTemplateVersion(presetKey string) string

func EmbeddedBuiltInPresetPrompt

func EmbeddedBuiltInPresetPrompt(presetKey string) *string

func ExtractSkillArchiveToDir

func ExtractSkillArchiveToDir(data []byte, destDir string) error

func InstructionTemplateVersionForPreset

func InstructionTemplateVersionForPreset(definitions []Definition, preamble string, moduleKeys []string) string

func NormalizeToolNames

func NormalizeToolNames(names []string) []string

func RefToCore

func RefToCore(ref ResolvedRef) agentcore.SkillRef

func RenderRuntimeToolNamesInInstructions

func RenderRuntimeToolNamesInInstructions(instructions string) string

func RenderRuntimeToolNamesInInstructionsForRuntime

func RenderRuntimeToolNamesInInstructionsForRuntime(instructions, runtimeKind string) string

func RequestUserInputUsesRuntimeBridge

func RequestUserInputUsesRuntimeBridge(policy Policy, runtimeKind string) bool

func ReviewCheckpointFencedBlockLabel

func ReviewCheckpointFencedBlockLabel(policy Policy, runtimeKind string) string

func SkillRefsForKeys

func SkillRefsForKeys(keys []string) []agentcore.SkillRef

func SkillVersionForBytes

func SkillVersionForBytes(data []byte) string

func SortedUniqueStrings

func SortedUniqueStrings(values []string) []string

func StageResolvedInto

func StageResolvedInto(ctx context.Context, resolution Resolution, opts StageOptions) error

func SyncRuntimeSkillRoot

func SyncRuntimeSkillRoot(srcRoot, destRoot string) error

func ValidateRuntimeAndTools

func ValidateRuntimeAndTools(runtimeKind string, allowedTools []string, definitions []Definition) error

Types

type ActiveSelection

type ActiveSelection struct {
	Refs         []agentcore.SkillRef
	Definitions  []Definition
	Instructions string
	Policy       Policy
}

func SelectActiveSkills

func SelectActiveSkills(refs []agentcore.SkillRef, definitions []Definition, ctx ActiveSelectionContext) ActiveSelection

type ActiveSelectionContext

type ActiveSelectionContext struct {
	PresetKey     string
	TargetType    string
	PlanningStage string
}

type Catalog

type Catalog struct {
	Skills []CatalogEntry `json:"skills"`
}

func ListCatalog

func ListCatalog(definitions []Definition) Catalog

func ListEmbeddedBuiltInCatalog

func ListEmbeddedBuiltInCatalog() Catalog

type CatalogEntry

type CatalogEntry struct {
	Key               string   `json:"key"`
	Title             string   `json:"title"`
	Description       string   `json:"description"`
	Instructions      string   `json:"instructions"`
	SourceKind        string   `json:"source_kind"`
	RequiredTools     []string `json:"required_tools,omitempty"`
	SupportedRuntimes []string `json:"supported_runtimes,omitempty"`
	Presets           []string `json:"presets,omitempty"`
}

type ContextualWorkspaceLookup

type ContextualWorkspaceLookup interface {
	GetByIDForContext(ctx context.Context, req LookupRequest) (*WorkspaceSkill, error)
	GetActiveByKeyForContext(ctx context.Context, req LookupRequest) (*WorkspaceSkill, error)
}

type Definition

type Definition struct {
	Key               string
	Title             string
	Description       string
	SourceKind        string
	PackagePath       string
	Instructions      string
	RequiredTools     []string
	SupportedRuntimes []string
	Policy            Policy
	Interface         Interface
}

func LoadBuiltInSkills

func LoadBuiltInSkills(skillFS fs.FS, root string) ([]Definition, error)

func LoadEmbeddedBuiltIns

func LoadEmbeddedBuiltIns() ([]Definition, error)

func LoadPackage

func LoadPackage(skillFS fs.FS, packagePath string, sourceKind string) (Definition, error)

func LoadSkillArchive

func LoadSkillArchive(data []byte, sourceKind string) (Definition, error)

func MustLoadEmbeddedBuiltIns

func MustLoadEmbeddedBuiltIns() []Definition

type HTTPPackageStore

type HTTPPackageStore struct {
	BaseURL string
	Token   string
	Client  *http.Client
}

func (HTTPPackageStore) GetObject

func (s HTTPPackageStore) GetObject(ctx context.Context, key string) ([]byte, error)

type HTTPWorkspaceLookup

type HTTPWorkspaceLookup struct {
	BaseURL string
	Token   string
	Client  *http.Client
}

func (HTTPWorkspaceLookup) GetActiveByKey

func (l HTTPWorkspaceLookup) GetActiveByKey(ctx context.Context, appID, key string) (*WorkspaceSkill, error)

func (HTTPWorkspaceLookup) GetActiveByKeyForContext

func (l HTTPWorkspaceLookup) GetActiveByKeyForContext(ctx context.Context, req LookupRequest) (*WorkspaceSkill, error)

func (HTTPWorkspaceLookup) GetByID

func (l HTTPWorkspaceLookup) GetByID(ctx context.Context, appID, id string) (*WorkspaceSkill, error)

func (HTTPWorkspaceLookup) GetByIDForContext

func (l HTTPWorkspaceLookup) GetByIDForContext(ctx context.Context, req LookupRequest) (*WorkspaceSkill, error)

type InteractionContract

type InteractionContract struct {
	Kind       string                          `json:"kind,omitempty" yaml:"kind,omitempty"`
	Schema     string                          `json:"schema,omitempty" yaml:"schema,omitempty"`
	Transports map[string]InteractionTransport `json:"transports,omitempty" yaml:"transports,omitempty"`
}

func NormalizeInteractionContracts

func NormalizeInteractionContracts(contracts []InteractionContract) []InteractionContract

type InteractionTransport

type InteractionTransport struct {
	Type       string `json:"type,omitempty" yaml:"type,omitempty"`
	ToolName   string `json:"tool_name,omitempty" yaml:"tool_name,omitempty"`
	BlockLabel string `json:"block_label,omitempty" yaml:"block_label,omitempty"`
}

type Interface

type Interface struct {
	DisplayName      string `json:"display_name,omitempty" yaml:"display_name"`
	ShortDescription string `json:"short_description,omitempty" yaml:"short_description"`
	IconSmall        string `json:"icon_small,omitempty" yaml:"icon_small"`
	IconLarge        string `json:"icon_large,omitempty" yaml:"icon_large"`
	BrandColor       string `json:"brand_color,omitempty" yaml:"brand_color"`
	DefaultPrompt    string `json:"default_prompt,omitempty" yaml:"default_prompt"`
}

type LookupContext

type LookupContext struct {
	AppID    string                 `json:"app_id"`
	AgentID  string                 `json:"agent_id,omitempty"`
	RunID    string                 `json:"run_id,omitempty"`
	Target   agentcore.TargetRef    `json:"target,omitempty"`
	Trigger  map[string]interface{} `json:"trigger,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type LookupRequest

type LookupRequest struct {
	LookupContext
	SkillID string `json:"skill_id,omitempty"`
	Key     string `json:"key,omitempty"`
}

type NativeActiveSelection

type NativeActiveSelection = ActiveSelection

func SelectNativeActiveSkills

func SelectNativeActiveSkills(refs []agentcore.SkillRef, definitions []Definition, ctx NativeActiveSelectionContext) NativeActiveSelection

type NativeActiveSelectionContext

type NativeActiveSelectionContext = ActiveSelectionContext

Compatibility aliases keep internal callers source-compatible while active selection is no longer native-runtime-specific.

type PackageStore

type PackageStore interface {
	GetObject(ctx context.Context, key string) ([]byte, error)
}

type PackageStoreRegistry

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

func NewPackageStoreRegistry

func NewPackageStoreRegistry() *PackageStoreRegistry

func (*PackageStoreRegistry) Register

func (r *PackageStoreRegistry) Register(appID string, store PackageStore) error

func (*PackageStoreRegistry) Store

func (r *PackageStoreRegistry) Store(appID string) (PackageStore, bool)

type Policy

type Policy struct {
	AllowImplicitInvocation            *bool                 `json:"allow_implicit_invocation,omitempty" yaml:"allow_implicit_invocation,omitempty"`
	CompletionRequiresInteractionKinds []string              `json:"completion_requires_interaction_kinds,omitempty" yaml:"completion_requires_interaction_kinds,omitempty"`
	InteractionContracts               []InteractionContract `json:"interaction_contracts,omitempty" yaml:"interaction_contracts,omitempty"`
}

func AggregatePolicy

func AggregatePolicy(definitions []Definition) Policy

func (Policy) InteractionContract

func (p Policy) InteractionContract(kind string) (InteractionContract, bool)

type PresetSkillBundle

type PresetSkillBundle struct {
	Preamble  string
	SkillKeys []string
}

func BuiltInPresetSkillBundleForPreset

func BuiltInPresetSkillBundleForPreset(presetKey string) (PresetSkillBundle, bool)

type Registry

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

func NewDefaultRegistry

func NewDefaultRegistry() *Registry

func NewRegistry

func NewRegistry(definitions ...Definition) *Registry

func (*Registry) BuiltIn

func (r *Registry) BuiltIn(key string) (Definition, bool)

func (*Registry) ListBuiltIns

func (r *Registry) ListBuiltIns() []Definition

func (*Registry) RegisterBuiltIn

func (r *Registry) RegisterBuiltIn(definition Definition)

func (*Registry) Resolve

func (r *Registry) Resolve(ctx context.Context, appID string, refs []agentcore.SkillRef) (Resolution, error)

func (*Registry) ResolveForContext

func (r *Registry) ResolveForContext(ctx context.Context, lookupCtx LookupContext, refs []agentcore.SkillRef) (Resolution, error)

func (*Registry) SetWorkspaceLookup

func (r *Registry) SetWorkspaceLookup(lookup WorkspaceLookup)

func (*Registry) SetWorkspaceLookupForApp

func (r *Registry) SetWorkspaceLookupForApp(appID string, lookup WorkspaceLookup)

func (*Registry) WorkspaceLookupForApp

func (r *Registry) WorkspaceLookupForApp(appID string) WorkspaceLookup

type RepositoryStageReport

type RepositoryStageReport struct {
	Staged   []string
	Skipped  map[string]string
	Limited  bool
	Manifest string
}

RepositoryStageReport says what repository staging did, for logging.

func StageRepositorySkills

func StageRepositorySkills(checkoutRoot, destRoot string, reserved map[string]bool) (RepositoryStageReport, error)

StageRepositorySkills discovers `.agents/skills/*/SKILL.md` directly under checkoutRoot, copies each accepted skill into destRoot/repository/<key>, and merges the entries into the staged manifest so find_skills and read_skill see them. reserved holds keys owned by built-in or workspace skills; those win on collision. Nothing under a skill is executed.

type Resolution

type Resolution struct {
	Refs                   []ResolvedRef
	CoreRefs               []agentcore.SkillRef
	Definitions            []Definition
	InstructionRefs        []agentcore.SkillRef
	InstructionDefinitions []Definition
	AvailableRefs          []agentcore.SkillRef
	AvailableDefinitions   []Definition
	UsesExplicitRoles      bool
	Instructions           string
	Policy                 Policy
}

func ReconcileResolutionFromStagedPackages

func ReconcileResolutionFromStagedPackages(resolution Resolution, destRoot string) (Resolution, error)

ReconcileResolutionFromStagedPackages makes the versioned package content authoritative for the run-time skill contract. Workspace lookup metadata is useful for discovery, but it can lag behind the package and must not be able to silently drop required tools or completion-interaction policy defined by the staged SKILL.md package.

func SelectActiveResolution

func SelectActiveResolution(resolution Resolution, ctx ActiveSelectionContext) Resolution

SelectActiveResolution narrows phase- and target-selectable built-in skills for every runtime adapter. Available skills remain discoverable, while the matching subset becomes active for policy and completion enforcement.

func SelectNativeActiveResolution

func SelectNativeActiveResolution(resolution Resolution, ctx NativeActiveSelectionContext) Resolution

type ResolvedRef

type ResolvedRef struct {
	SkillID    string          `json:"skill_id,omitempty"`
	Key        string          `json:"key,omitempty"`
	VersionKey string          `json:"version_key,omitempty"`
	Version    string          `json:"version,omitempty"`
	Config     json.RawMessage `json:"config,omitempty"`
}

func NormalizeRefs

func NormalizeRefs(refs []agentcore.SkillRef) []ResolvedRef

func RefFromCore

func RefFromCore(ref agentcore.SkillRef) ResolvedRef

type SkillDependency

type SkillDependency struct {
	Type        string `json:"type,omitempty" yaml:"type"`
	Value       string `json:"value,omitempty" yaml:"value"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Transport   string `json:"transport,omitempty" yaml:"transport,omitempty"`
	URL         string `json:"url,omitempty" yaml:"url,omitempty"`
}

type StageOptions

type StageOptions struct {
	Lookup        WorkspaceLookup
	PackageStore  PackageStore
	LookupContext LookupContext
	DestRoot      string
	RuntimeKind   string
}

type WorkspaceLookup

type WorkspaceLookup interface {
	GetByID(ctx context.Context, appID, id string) (*WorkspaceSkill, error)
	GetActiveByKey(ctx context.Context, appID, key string) (*WorkspaceSkill, error)
}

type WorkspaceSkill

type WorkspaceSkill struct {
	ID                string    `json:"id"`
	Key               string    `json:"key"`
	VersionKey        string    `json:"version_key"`
	Title             string    `json:"title"`
	Description       string    `json:"description"`
	SourceKind        string    `json:"source_kind"`
	Instructions      string    `json:"instructions"`
	RequiredTools     []string  `json:"required_tools,omitempty"`
	SupportedRuntimes []string  `json:"supported_runtimes,omitempty"`
	Policy            Policy    `json:"policy,omitempty"`
	Interface         Interface `json:"interface,omitempty"`
	PackageObjectKey  string    `json:"package_object_key,omitempty"`
	PackageFileName   string    `json:"package_file_name,omitempty"`
	PackageChecksum   string    `json:"package_checksum,omitempty"`
	PackageSize       int64     `json:"package_size,omitempty"`
	Archived          bool      `json:"is_archived,omitempty"`
}

Jump to

Keyboard shortcuts

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