skills

type ContextProviderOptions struct {
	// SourceID is the identifier for the provider's source in the resulting context.
	// Defaults to "skills" if not provided.
	SourceID string

	// SkillFilter optionally filters skills loaded from inline skills and sources.
	// Returning true keeps a skill; returning false excludes it.
	SkillFilter func(*Skill) bool

	// Skills provides in-memory skills to register with the provider.
	Skills []*Skill

	// Sources provides external skill sources to register with the provider.
	Sources []Source

	// SkillsInstructionPrompt is a custom system prompt template.
	// When nil, a default template is used.
	//
	// The template must contain {skills}.
	SkillsInstructionPrompt *string

	// DisableLoadSkillApproval disables approval for the load_skill tool.
	// When false (the default), invoking load_skill requires approval.
	DisableLoadSkillApproval bool

	// DisableReadSkillResourceApproval disables approval for the
	// read_skill_resource tool. When false (the default), invoking
	// read_skill_resource requires approval.
	DisableReadSkillResourceApproval bool

	// DisableRunSkillScriptApproval disables approval for the
	// run_skill_script tool. When false (the default), invoking
	// run_skill_script requires approval.
	DisableRunSkillScriptApproval bool

	// IncludeDetailedErrors includes script execution error details in the
	// run_skill_script result returned to the model.
	//
	// When false, script execution errors are returned to the caller so tool
	// invocation middleware can apply its own error-detail policy. When true,
	// the exception message is appended to the tool result so the model can
	// retry with different arguments. Only enable this for trusted skills and
	// scripts because raw error messages may contain prompt-injection content.
	IncludeDetailedErrors bool

	// DisableCaching rebuilds instructions and tools for every invocation.
	DisableCaching bool

	// CacheIsolationKeySelector selects the cache bucket for an invocation.
	// A nil selector, or a nil key returned by the selector, uses the shared
	// cache bucket. Keys should be stable and low-cardinality.
	CacheIsolationKeySelector func(context.Context, agent.InvokingContext) *string

	// RefreshInterval controls how long a cached result remains fresh. A nil
	// interval never expires the cache. A zero or negative interval refreshes
	// on every invocation.
	RefreshInterval *time.Duration

	// DisableSourceDeduplication preserves duplicate skill names from the configured
	// skills and sources instead of removing later duplicates.
	DisableSourceDeduplication bool

	// Logger is an optional structured logger for provider diagnostics.
	Logger *slog.Logger
}

type Frontmatter struct {
	Name          string
	Description   string
	License       string
	Compatibility string
	AllowedTools  string
	Metadata      map[string]any
}

type Resource struct {
	Name                 string
	Description          string
	Read                 func(context.Context) (any, error)
	AdditionalProperties map[string]any
}

type Script struct {
	Name        string
	Description string
	// ParametersSchema is an optional JSON schema string describing the argument
	// format expected by the script. When set, file-based skills include the schema
	// in the skill's <available_scripts> block so the LLM knows how to format
	// arguments. Empty means no schema.
	ParametersSchema     string
	Run                  func(context.Context, *Skill, []string) (any, error)
	AdditionalProperties map[string]any
}

type ScriptRunner func(context.Context, *Skill, *Script, []string) (any, error)

type Skill struct {
	Frontmatter Frontmatter
	// GetContent lazily loads the skill's instruction text. For file-based skills
	// this is the raw SKILL.md file content. For code-defined skills this may be
	// a synthesized document containing name, description, and body.
	GetContent           func(context.Context) (string, error)
	Resources            []Resource
	Scripts              []Script
	AdditionalProperties map[string]any
}

type Source interface {
	Skills(context.Context) ([]*Skill, error)
}

type SourceFunc func(context.Context) ([]*Skill, error)