spec

type LoadArgs struct {
	Skills []SkillHandle `json:"skills"`
	Mode   LoadMode      `json:"mode,omitempty"` // default: replace
}

type LoadMode string

type LoadOut struct {
	ActiveSkills []SkillHandle `json:"activeSkills"`
}

type ProviderSkillIndexRecord struct {
	Key ProviderSkillKey `json:"key"`

	Name        string `json:"name"`
	Description string `json:"description"`
	DisplayName string `json:"displayName,omitempty"`

	// Insert is parsed from SKILL.md frontmatter field "insert".
	// Missing/empty defaults to "instructions".
	Insert SkillInsert `json:"insert"`

	Arguments []SkillArgument `json:"arguments,omitempty"`

	Resources SkillResourceInfo `json:"resources"`

	RawFrontmatter map[string]any `json:"rawFrontmatter,omitempty"`

	Warnings []string `json:"warnings,omitempty"`

	Digest    string `json:"digest,omitempty"`
	SkillBody string `json:"skillBody,omitempty"` // optional cached body (e.g. SKILL.md without frontmatter)
}

type ProviderSkillKey struct {
	Type     string `json:"type"`
	Name     string `json:"name"`
	Location string `json:"location"`
}

type ReadResourceArgs struct {
	SkillName     string `json:"skillName"`
	SkillLocation string `json:"skillLocation"`

	// ResourceLocation is provider-defined; for fs providers this is typically a relative file path.
	ResourceLocation string `json:"resourceLocation"`

	Encoding ReadResourceEncoding `json:"encoding,omitempty"` // default: text
}

type ReadResourceEncoding string

type RenderSkillBodyResult struct {
	Text string `json:"text"`

	AppliedArguments    map[string]string `json:"appliedArguments,omitempty"`
	UnknownPlaceholders []string          `json:"unknownPlaceholders,omitempty"`
	Warnings            []string          `json:"warnings,omitempty"`
}

type RenderSkillOut struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	DisplayName string      `json:"displayName,omitempty"`
	Insert      SkillInsert `json:"insert"`

	Resources SkillResourceInfo `json:"resources"`

	Text string `json:"text"`

	Arguments        []SkillArgument   `json:"arguments,omitempty"`
	AppliedArguments map[string]string `json:"appliedArguments,omitempty"`

	RawFrontmatter map[string]any `json:"rawFrontmatter,omitempty"`
	Warnings       []string       `json:"warnings,omitempty"`
}

type RunScriptArgs struct {
	SkillName     string `json:"skillName"`
	SkillLocation string `json:"skillLocation"`

	// ScriptLocation is provider-defined; for fs providers this is typically a relative script file path.
	ScriptLocation string `json:"scriptLocation"`

	Args []string          `json:"args,omitempty"`
	Env  map[string]string `json:"env,omitempty"`

	// WorkDir is provider-defined; for fs providers this is typically a relative directory under the skill base.
	WorkDir string `json:"workDir,omitempty"`
}

type RunScriptOut struct {
	Location   string `json:"location"`
	ExitCode   int    `json:"exitCode"`
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	TimedOut   bool   `json:"timedOut,omitempty"`
	DurationMS int64  `json:"durationMS,omitempty"`
}

type SessionID string

type SkillActivity string

type SkillArgument struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Default     string `json:"default,omitempty"`
}

type SkillDef struct {
	Type     string `json:"type"`
	Name     string `json:"name"`
	Location string `json:"location"`
}

type SkillHandle struct {
	// Name is the catalog-computed LLM-visible name (usually the real name;
	// may be disambiguated with an opaque suffix like "my-skill#1a2b3c4d").
	Name string `json:"name"`

	// Location is the user-provided and provider-interpreted base location for the skill.
	Location string `json:"location"`
}

type SkillInsert string

type SkillProvider interface {
	// Type returns the provider type key (e.g. "fs", "s3").
	Type() string

	// Index validates and returns metadata for the skill identified by def.
	// Providers may canonicalize Location in the returned ProviderSkillIndexRecord.Key.
	Index(ctx context.Context, def SkillDef) (ProviderSkillIndexRecord, error)

	// LoadBody returns the prompt-injectable SKILL.md body (frontmatter removed).
	LoadBody(ctx context.Context, key ProviderSkillKey) (string, error)

	// ReadResource reads a resource relative to the skill base location.
	// The meaning/format of resourceLocation is provider-defined (for fs it's typically a relative file path).
	ReadResource(
		ctx context.Context,
		key ProviderSkillKey,
		resourceLocation string,
		encoding ReadResourceEncoding,
	) ([]llmtoolsgoSpec.ToolOutputUnion, error)

	// RunScript executes a provider-scoped script identified by scriptLocation.
	// Providers define/enforce constraints (e.g. must be under scripts/).
	RunScript(
		ctx context.Context,
		key ProviderSkillKey,
		scriptLocation string,
		args []string,
		env map[string]string,
		workDir string,
	) (RunScriptOut, error)
}

type SkillRecord struct {
	Def SkillDef `json:"def"`

	Name        string `json:"name"`
	Description string `json:"description"`
	DisplayName string `json:"displayName,omitempty"`

	// Insert is the FlexiGPT insertion hint parsed from SKILL.md.
	// Defaults to "instructions".
	Insert SkillInsert `json:"insert"`

	Arguments []SkillArgument `json:"arguments,omitempty"`

	Resources SkillResourceInfo `json:"resources"`

	// RawFrontmatter preserves the parsed SKILL.md YAML frontmatter for callers that want
	// compatibility metadata that this runtime does not interpret.
	RawFrontmatter map[string]any `json:"rawFrontmatter,omitempty"`

	Warnings []string `json:"warnings,omitempty"`

	Digest string `json:"digest,omitempty"`
}

type SkillResourceInfo struct {
	// HasResources is true when the provider advertises at least one additional resource.
	HasResources bool `json:"hasResources"`

	// TotalCount is the total number of additional resources found, even when Locations is truncated.
	TotalCount int `json:"totalCount"`

	// Locations contains up to MaxSkillResourceLocations provider-defined resource locations.
	Locations []string `json:"locations,omitempty"`

	// MoreLocations is true when more locations exist than are included in Locations.
	MoreLocations bool `json:"moreLocations"`
}

type UnloadArgs struct {
	Skills []SkillHandle `json:"skills,omitempty"`
	All    bool          `json:"all,omitempty"`
}

type UnloadOut struct {
	ActiveSkills []SkillHandle `json:"activeSkills"`
}