# skill-catalog Specification

## Purpose
Provides a local, read-only catalog of Skills (knowledge and flow-template) synced from the Subscription Platform, queryable by list, search, and id without per-query network round-trips.
## Requirements
### Requirement: Unified Skill data model
The system SHALL represent every Skill with shared metadata (id, name, description, version, tags, source/subscription id, updated_at) and a `kind` discriminator of either `knowledge` or `flow_template`, so both kinds can be listed and searched through one catalog.

#### Scenario: Knowledge skill has content
- **WHEN** a Skill with `kind = knowledge` is stored
- **THEN** it includes a `content` field (structured instructional text/markdown) in addition to the shared metadata

#### Scenario: Flow-template skill has steps and parameters
- **WHEN** a Skill with `kind = flow_template` is stored
- **THEN** it includes an ordered `steps` list (each referencing a tool name and an args template that may contain `{param}` placeholders) and a `parameters` schema (name, type, required, description) in addition to the shared metadata

### Requirement: Local skill storage
The system SHALL persist the synced Skill Catalog locally so that skills can be listed and fetched without a live round-trip to the Subscription Platform for every query.

#### Scenario: Skill readable after sync
- **WHEN** a skill has been synced from the Subscription Platform into the local catalog
- **THEN** subsequent list/search/get operations return that skill without requiring a new network call to the Subscription Platform

#### Scenario: Local catalog is not independently authored
- **WHEN** a caller attempts to create or edit a skill directly in the local catalog (outside of a sync operation)
- **THEN** the system SHALL reject or ignore the write, since the Subscription Platform is the sole source of truth for skill content

### Requirement: Skill search and query
The system SHALL provide functions to list all currently visible skills, search skills by name/tag/description text, and fetch a single skill by id.

#### Scenario: List returns only visible skills
- **WHEN** the catalog is queried for the list of skills visible to the current caller
- **THEN** it returns only skills whose subscription is currently active for that caller, sorted in a stable order (e.g. by name)

#### Scenario: Search matches on name, tags, or description
- **WHEN** a search query string matches a skill's name, a tag, or its description
- **THEN** that skill is included in the search results

#### Scenario: Get by id returns full content
- **WHEN** a caller fetches a skill by its id
- **THEN** the system returns the full skill record, including `content` for knowledge skills or `steps`/`parameters` for flow-template skills

#### Scenario: Get by id for unknown or invisible skill
- **WHEN** a caller fetches a skill id that does not exist, or exists but is not currently visible to them (subscription inactive)
- **THEN** the system returns a clear "not found" result rather than leaking the skill's existence or content

### Requirement: Flow-template tool reference validation
The system SHALL validate that a flow-template skill's referenced tool names correspond to currently registered device-capability tools, and SHALL mark a flow-template skill as invalid/unavailable rather than allowing it to be fetched successfully if a referenced tool does not exist.

#### Scenario: Valid flow template
- **WHEN** every step in a flow-template skill references a tool name that is currently registered
- **THEN** the skill is fetchable and returned normally

#### Scenario: Flow template references an unknown tool
- **WHEN** a flow-template skill's steps reference a tool name that is not currently registered (e.g. renamed or removed)
- **THEN** fetching that skill returns a clear "skill unavailable/invalid" result instead of a step list containing a dangling tool reference