# skill-authoring Specification

## Purpose
TBD - created by archiving change skill-learning-runtime. Update Purpose after archive.
## Requirements
### Requirement: Synthesis triggers only on successful task completion
The system SHALL synthesize a flow-template skill only when a task's final status is `succeeded`, and SHALL NOT attempt synthesis for a task that failed, was cancelled, or is still running.

#### Scenario: Successful task triggers synthesis
- **WHEN** a task completes with status `succeeded` and Skill Authoring is enabled
- **THEN** the system reads that task's timeline and goal and produces a flow-template skill candidate

#### Scenario: Failed task does not trigger synthesis
- **WHEN** a task completes with status `failed` (or is cancelled/still running)
- **THEN** the system does not synthesize any skill from that task's timeline

### Requirement: Skill Authoring defaults to disabled
The system SHALL leave Skill Authoring disabled by default in configuration, so applying this capability does not change the cost or latency of any existing task run until a caller explicitly enables it.

#### Scenario: Default configuration performs no synthesis
- **WHEN** a task completes successfully and Skill Authoring has not been explicitly enabled in configuration
- **THEN** the system performs no synthesis work and the task's completion path behaves exactly as it would without this capability

#### Scenario: Explicit enable activates synthesis
- **WHEN** an operator enables Skill Authoring in configuration
- **THEN** subsequently completed successful tasks are eligible for synthesis

### Requirement: Flow-template skill synthesized from executed tool-call sequence
The system SHALL derive a flow-template skill's ordered steps from the sequence of mutating tool calls (e.g. `tap`, `swipe`, `input_text`, `launch_app`) recorded in the completed task's timeline, in the order they were executed, and SHALL exclude read-only/observational tool calls (e.g. `describe_screen`, `screenshot`, `ui_tree`) from the synthesized step list.

#### Scenario: Mutating steps are included in order
- **WHEN** a task's timeline contains a sequence of `launch_app`, `tap`, `input_text`, `tap` tool calls that all succeeded
- **THEN** the synthesized skill's steps list contains those four steps in that same order

#### Scenario: Read-only observation calls are excluded
- **WHEN** a task's timeline includes `describe_screen` or `screenshot` calls interleaved with mutating calls
- **THEN** the synthesized skill's steps list omits those read-only calls and retains only the mutating steps

### Requirement: Parameter abstraction from cross-execution argument diffing
The system SHALL abstract a synthesized skill's step arguments into named parameters by comparing the newly executed argument values against a previously stored skill with the same tool-name step sequence, promoting any argument value that differs between the two executions into a named placeholder, and SHALL leave a first-time synthesis (no prior matching skeleton) with zero parameters.

#### Scenario: First execution of a flow has no parameters
- **WHEN** no previously stored skill shares the newly executed tool-name sequence
- **THEN** the synthesized skill is stored with its literal argument values and an empty parameters list

#### Scenario: Second, divergent execution promotes a differing value to a parameter
- **WHEN** a later successful task executes the same tool-name sequence as a stored skill but with a different literal value at one argument position
- **THEN** the system promotes that argument position to a named parameter in the skill's `parameters` schema and replaces the literal in `steps` with a `{param}` placeholder referencing it

#### Scenario: Identical repeated execution does not spuriously add parameters
- **WHEN** a later successful task executes the same tool-name sequence as a stored skill with identical argument values at every position
- **THEN** the system does not introduce any new parameter for that skill

### Requirement: Locally-authored skills are stored separately from synced skills
The system SHALL persist locally-synthesized flow-template skills tagged with a `source` of `local-synthesis`, in a store owned by this capability, and SHALL NOT write into or modify the externally-synced skill catalog store or its sync-only write contract.

#### Scenario: Synthesized skill is tagged as locally-authored
- **WHEN** a flow-template skill is synthesized from a completed task
- **THEN** its stored record has `source = "local-synthesis"` and no subscription identifier

#### Scenario: Synced skill catalog is untouched by synthesis
- **WHEN** a skill is synthesized and stored by this capability
- **THEN** no record in the externally-synced skill catalog store is created, modified, or removed as a result