spec

type AllSkillBundles struct {
	Bundles map[bundleitemutils.BundleID]SkillBundle `json:"bundles"`
}

type DeleteSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
}

type DeleteSkillBundleResponse struct{}

type DeleteSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
}

type DeleteSkillResponse struct{}

type GetSkillRequest struct {
	BundleID        bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug       SkillSlug                `path:"skillSlug" required:"true"`
	IncludeDisabled bool                     `                                 query:"includeDisabled"`
}

type GetSkillResponse struct{ Body *Skill }

type ListSkillBundlesRequest struct {
	BundleIDs       []bundleitemutils.BundleID `query:"bundleIDs"`
	IncludeDisabled bool                       `query:"includeDisabled"`
	PageSize        int                        `query:"pageSize"`
	PageToken       string                     `query:"pageToken"`
}

type ListSkillBundlesResponse struct {
	Body *ListSkillBundlesResponseBody
}

type ListSkillBundlesResponseBody struct {
	SkillBundles  []SkillBundle `json:"skillBundles"`
	NextPageToken *string       `json:"nextPageToken,omitempty"`
}

type ListSkillPhase string

type ListSkillsRequest struct {
	BundleIDs           []bundleitemutils.BundleID    `query:"bundleIDs"`
	Types               []SkillType                   `query:"types"`
	Inserts             []agentskillsSpec.SkillInsert `query:"inserts"`
	Tags                []string                      `query:"tags"`
	IncludeDisabled     bool                          `query:"includeDisabled"`
	IncludeMissing      bool                          `query:"includeMissing"`
	RecommendedPageSize int                           `query:"recommendedPageSize"`
	PageToken           string                        `query:"pageToken"`
}

type ListSkillsResponse struct {
	Body *ListSkillsResponseBody
}

type ListSkillsResponseBody struct {
	SkillListItems []SkillListItem `json:"skillListItems"`
	NextPageToken  *string         `json:"nextPageToken,omitempty"`
}

type PatchSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
	Body     *PatchSkillBundleRequestBody
}

type PatchSkillBundleRequestBody struct {
	IsEnabled bool `json:"isEnabled" required:"true"`
}

type PatchSkillBundleResponse struct{}

type PatchSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PatchSkillRequestBody
}

type PatchSkillRequestBody struct {
	// Built-in skills: only IsEnabled is supported.
	// User skills: IsEnabled, Location, and metadata fields are supported.
	IsEnabled   *bool     `json:"isEnabled,omitempty"`
	Location    *string   `json:"location,omitempty"`
	DisplayName *string   `json:"displayName,omitempty"`
	Description *string   `json:"description,omitempty"`
	Tags        *[]string `json:"tags,omitempty"` // pointer so caller can send [] to clear
}

type PatchSkillResponse struct{}

type PutSkillArtifactRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PutSkillArtifactRequestBody
}

type PutSkillArtifactRequestBody struct {
	// Name is the Agent Skills artifact name. If empty, SkillSlug is used.
	// For filesystem skills, this is also used as the managed directory name.
	Name string `json:"name,omitempty"`

	IsEnabled bool `json:"isEnabled" required:"true"`

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

	// Insert defaults to instructions.
	Insert agentskillsSpec.SkillInsert `json:"insert,omitempty"`

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

	// Tags are stored as app-managed tags and are also written into the
	// managed SKILL.md frontmatter as source tags.
	Tags []string `json:"tags,omitempty"`

	// MarkdownBody is written after YAML frontmatter in SKILL.md. It may be
	// empty for resource-oriented skills.
	MarkdownBody string `json:"markdownBody"`
}

type PutSkillArtifactResponse struct{ Body *PutSkillArtifactResponseBody }

type PutSkillArtifactResponseBody struct {
	Skill Skill `json:"skill"`
}

type PutSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
	Body     *PutSkillBundleRequestBody
}

type PutSkillBundleRequestBody struct {
	Slug        bundleitemutils.BundleSlug `json:"slug"                  required:"true"`
	DisplayName string                     `json:"displayName"           required:"true"`
	IsEnabled   bool                       `json:"isEnabled"             required:"true"`
	Description string                     `json:"description,omitempty"`
}

type PutSkillBundleResponse struct{}

type PutSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PutSkillRequestBody
}

type PutSkillRequestBody struct {
	SkillType SkillType `json:"skillType" required:"true"`
	Location  string    `json:"location"  required:"true"`
	Name      string    `json:"name"      required:"true"`
	IsEnabled bool      `json:"isEnabled" required:"true"`

	DisplayName string   `json:"displayName,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
}

type PutSkillResponse struct{}

type Skill struct {
	SchemaVersion string    `json:"schemaVersion"`
	ID            SkillID   `json:"id"`   // UUID-v7
	Slug          SkillSlug `json:"slug"` // unique slug identifier

	Type     SkillType `json:"type"`
	Location string    `json:"location"` // opaque provider/app location; user-created fs skills usually use an absolute base dir.
	Name     string    `json:"name"`     // name of the skill inside SKILL.md.

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

	// Tags are application-managed tags used for app filtering and
	// organization. Source tags from SKILL.md are exposed through runtime
	// projections rather than overwriting this field during indexing.
	Tags []string `json:"tags,omitempty"`

	// Parsed from SKILL.md frontmatter field "insert".
	// Missing/empty defaults to "instructions".
	Insert SkillInsert `json:"insert,omitempty"`

	// Parsed from SKILL.md frontmatter field "arguments".
	Arguments []SkillArgument `json:"arguments,omitempty"`

	// Runtime/provider-indexed resource metadata. Locations are provider-defined
	// values intended for use with skills-readresource.resourceLocation.
	Resources SkillResourceInfo `json:"resources"`

	// Full parsed YAML frontmatter. FlexiGPT only gives semantics to name,
	// description, insert, and arguments; other fields are preserved for callers.
	RawFrontmatter map[string]any `json:"rawFrontmatter,omitempty"`

	// Runtime/provider indexing metadata.
	RuntimeWarnings []string `json:"runtimeWarnings,omitempty"`
	Digest          string   `json:"digest,omitempty"`

	Presence *SkillPresence `json:"presence,omitempty"`

	IsEnabled bool `json:"isEnabled"`
	IsBuiltIn bool `json:"isBuiltIn"`

	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

type SkillArgument = agentskillsSpec.SkillArgument

type SkillBundle struct {
	SchemaVersion string          `json:"schemaVersion"`
	ID            SkillBundleID   `json:"id"` // UUID-v7
	Slug          SkillBundleSlug `json:"slug"`

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

	IsEnabled  bool      `json:"isEnabled"`
	IsBuiltIn  bool      `json:"isBuiltIn"`
	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`

	SoftDeletedAt *time.Time `json:"softDeletedAt,omitempty"`
}

type SkillBundleID = bundleitemutils.BundleID

type SkillBundlePageToken struct {
	BundleIDs       []bundleitemutils.BundleID `json:"ids,omitempty"` //nolint:tagliatelle // Page Token specific. // optional filter
	IncludeDisabled bool                       `json:"d,omitempty"`   //nolint:tagliatelle // Page Token specific.
	PageSize        int                        `json:"s"`             //nolint:tagliatelle // Page Token specific.
	CursorMod       string                     `json:"t,omitempty"`   //nolint:tagliatelle // Page Token specific.// RFC-3339-nano modifiedAt
	CursorID        bundleitemutils.BundleID   `json:"id,omitempty"`  //nolint:tagliatelle // Page Token specific.// tie-breaker
}

type SkillBundleSlug = bundleitemutils.BundleSlug

type SkillID = bundleitemutils.ItemID

type SkillInsert = agentskillsSpec.SkillInsert

type SkillListItem struct {
	BundleID   bundleitemutils.BundleID   `json:"bundleID"`
	BundleSlug bundleitemutils.BundleSlug `json:"bundleSlug"`

	SkillSlug SkillSlug `json:"skillSlug"`
	IsBuiltIn bool      `json:"isBuiltIn"`

	SkillDefinition Skill `json:"skillDefinition"`
}

type SkillPageToken struct {
	RecommendedPageSize int                           `json:"ps,omitempty"`   //nolint:tagliatelle // Page token specific.
	IncludeDisabled     bool                          `json:"d,omitempty"`    //nolint:tagliatelle // Page token specific.
	IncludeMissing      bool                          `json:"m,omitempty"`    //nolint:tagliatelle // Page token specific. // include presence=missing?
	BundleIDs           []bundleitemutils.BundleID    `json:"ids,omitempty"`  //nolint:tagliatelle // Page token specific. // optional filter
	Types               []SkillType                   `json:"ty,omitempty"`   //nolint:tagliatelle // Page token specific. // optional filter
	Inserts             []agentskillsSpec.SkillInsert `json:"in,omitempty"`   //nolint:tagliatelle // Page token specific.
	Tags                []string                      `json:"tags,omitempty"` //nolint:tagliatelle // Page token specific.
	Phase               ListSkillPhase                `json:"ph,omitempty"`   //nolint:tagliatelle //nolint:tagliatelle // Page token specific.
	BuiltInCursor       string                        `json:"bc,omitempty"`   //nolint:tagliatelle // opaque: last (bundleID|skillSlug)
	DirTok              string                        `json:"dt,omitempty"`   //nolint:tagliatelle // user cursor
}

type SkillPresence struct {
	Status SkillPresenceStatus `json:"status"`

	// LastCheckedAt is when we last attempted to validate presence.
	LastCheckedAt *time.Time `json:"lastCheckedAt,omitempty"`

	// LastSeenAt is when the location was last confirmed present.
	LastSeenAt *time.Time `json:"lastSeenAt,omitempty"`

	// MissingSince is set when we transition into "missing".
	MissingSince *time.Time `json:"missingSince,omitempty"`

	// LastCheckError is only meaningful when Status == "error".
	LastCheckError string `json:"lastCheckError,omitempty"`
}

type SkillPresenceStatus string

type SkillRef struct {
	BundleID  SkillBundleID `json:"bundleID"`
	SkillSlug SkillSlug     `json:"skillSlug"`
	SkillID   SkillID       `json:"skillID"`
}

type SkillResourceInfo = agentskillsSpec.SkillResourceInfo

type SkillSelection struct {
	SkillRef          SkillRef `json:"skillRef"`
	PreLoadAsActive   bool     `json:"preLoadAsActive"`
	UseAsInstructions bool     `json:"useAsInstructions"`
}

type SkillSlug = bundleitemutils.ItemSlug

type SkillType string