agentic-mobile-control/openspec/changes/skill-learning-runtime/specs/skill-authoring/spec.md

ADDED 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