agentic-mobile-control/openspec/specs/skill-catalog/spec.md

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