q792602257andClaude Opus 4.6
e5a12f9b74
Change is complete (24/24 tasks) per its declared scope (read-only local catalog + MCP tools + sync client contract). Management UI and the upstream Subscription Platform were explicitly out of scope. Deltas synced into three new main specs: skill-catalog, skill-mcp-tools, skill-subscription-sync. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
# 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
|