# skill-embedding-retrieval Specification

## Purpose
TBD - created by archiving change skill-learning-runtime. Update Purpose after archive.
## Requirements
### Requirement: Skill text embedded on synthesis and re-synthesis
The system SHALL compute and persist an embedding vector for each locally-authored skill's name, description, and originating goal text whenever that skill is first synthesized or a new version is stored, associated with that skill's id and version.

#### Scenario: New skill gains an embedding
- **WHEN** a flow-template skill is synthesized for the first time
- **THEN** the system computes an embedding vector from its name, description, and originating goal, and stores it alongside the skill record

#### Scenario: New version gains its own embedding
- **WHEN** a new version of an existing skill is created
- **THEN** the system computes and stores an embedding for that version, independent of any embedding stored for prior versions

### Requirement: Embedding failure degrades to non-retrievable-by-similarity, never blocks synthesis
The system SHALL NOT allow an embedding-provider failure (timeout, rate limit, disabled configuration, connection error) to prevent a skill from being synthesized or versioned; on such failure, the skill SHALL be stored without a similarity-searchable embedding.

#### Scenario: Embedding call fails but skill is still stored
- **WHEN** the embedding provider call fails or times out during synthesis of an otherwise-successful skill
- **THEN** the skill's flow-template record is still stored, and it is retrievable by exact name/id lookup but excluded from similarity-based retrieval results until a subsequent embedding attempt succeeds

### Requirement: Ranked retrieval of candidate skills by goal similarity
The system SHALL provide a function that, given a new goal string and a requested result count, returns locally-authored skills that have a stored embedding, ranked by descending semantic similarity between the goal and each skill's stored embedding.

#### Scenario: Similar goal returns matching skill highest-ranked
- **WHEN** a new goal is semantically similar to a previously-learned skill's originating goal
- **THEN** that skill appears in the ranked candidate results, ordered ahead of less-similar skills

#### Scenario: Requested count limits results
- **WHEN** a caller requests the top `k` candidate skills for a goal
- **THEN** the system returns at most `k` ranked results, even if more embedded skills exist

#### Scenario: No embedded skills yields an empty result
- **WHEN** no locally-authored skill currently has a stored embedding
- **THEN** the retrieval function returns an empty ranked list rather than raising an error

### Requirement: Retrieval scoped to locally-authored skills unless explicitly extended
The system SHALL restrict ranked candidate retrieval to skills stored by this capability's own local-synthesis store by default, and SHALL treat inclusion of externally-synced skills as a separate, explicit extension rather than an implicit default.

#### Scenario: Default retrieval excludes synced-only skills without embeddings
- **WHEN** the skill catalog contains externally-synced skills that have never been embedded by this capability
- **THEN** ranked candidate retrieval returns only locally-authored skills with stored embeddings, without erroring on the presence of unembedded synced skills