argent-create-flow

software-mansion/argent

Create, record, edit, replay, or repair reusable Argent flow YAML files for repeatable device interactions.

What is argent-create-flow?

Argent flows are replayable sequences stored as YAML files that automate repeatable device paths, profiling setups, and A/B comparisons. Use this skill when recording or replaying a device workflow, or before repeating three or more interactions; for one-off UI checks or acceptance tests, use argent-test-ui-flow or argent-qa-flows instead.

Record the first walkthrough of a device interaction before polishing into reusable YAML
Create e2e flows (with launch) or fragment flows (with executionPrerequisite) depending on process control needs
Edit and repair flows using semantic selectors (ids, text, accessibility labels) and relational scopes (within, after, next)
Replay complete flows end-to-end and validate screen changes with destination-only identity checks
Convert recorded steps to stable, deterministic YAML without changing their meaning
Handle coordinate fallbacks and resolve raw-gesture warnings through documented recovery procedures

How to install argent-create-flow

npx skills add https://github.com/software-mansion/argent --skill argent-create-flow

Prerequisites

Argent installed and configured
iOS simulator booted or physical iPhone connected (for hardware flows, pass device udid via --device flag)
Familiarity with Live authoring and Flow YAML reference documentation

Claude Code

Cursor

Windsurf

Cline

How to use argent-create-flow

1.Choose flow type: e2e (with launch) or fragment (with executionPrerequisite)
2.Start the recorder before the first launch or in-app action
3.Record one verified step at a time, using semantic targets (ids, text, labels) and recording checks when states appear
4.Record destination-only identity checks to prove every screen change
5.Polish the recorded steps by converting them to stable YAML without changing meaning
6.Audit the flow for coordinate warnings and raw-gesture exceptions, resolving via coordinate fallback gate if needed
7.Replay the complete flow end-to-end uninterrupted and verify the result

Use cases

Good for

Record a multi-step user journey on iOS simulator or physical device and replay it for regression testing
Set up profiling or A/B comparison flows that repeat the same interaction path consistently
Repair a failing flow by inspecting the first divergence and correcting the smallest justified unit
Create acceptance-criterion flows that prove every screen change and validate stable selectors
Automate a complex device workflow (login, navigation, data entry) that will be run multiple times

Who it's for

QA engineers building reusable test flows
Developers automating repeatable device interactions for profiling or comparison
Teams maintaining acceptance-driven regression tests on iOS
Anyone automating multi-step device workflows that will be executed more than once

argent-create-flow FAQ

When should I use argent-create-flow vs. argent-qa-flows or argent-test-ui-flow?

Use argent-create-flow for replayable device paths, profiling, A/B comparisons, or before repeating three or more interactions. Use argent-qa-flows for saved QA test cases with deterministic setup and two-pass proof, and argent-test-ui-flow for one-off UI checks or acceptance-driven regression tests.

Can I record a flow on a physical iPhone?

Yes, flows run on physical iPhones, but replay never auto-binds one. Pass the phone's udid as the device parameter (CLI --device), and only a connected phone can run. Note that pinch and rotate steps fail on hardware.

What makes a selector stable?

A stable selector is fixed by app code and survives account, data, time, count, order, locale, and environment changes. Prefer ids like 'settings-screen' over values like 'Today', 'Item 4', usernames, counters, or timestamps.

Can I insert steps that were not recorded?

No. Polish only executed behavior by converting recorded steps without changing meaning. The only unrecorded insertions allowed are planned snapshots, navigation idle checks, and documented Chromium packaging launch steps.

What should I do if replay fails?

Follow the Reliability and recovery guide: inspect the first divergence, correct the smallest justified unit, audit, and replay the full flow. Stop after two unsuccessful correction cycles and never weaken a requested check to obtain a pass.

Full instructions (SKILL.md)

Source of truth, from software-mansion/argent.

name: argent-create-flow description: Create, record, edit, replay, or repair reusable Argent flow YAML files. Use when the user asks to record or replay a repeatable device path, set up profiling or an A/B comparison, or invoke the authoring engine behind argent-qa-flows. Also use before repeating three or more interactions. For one-off UI checks, acceptance-driven regression tests, or screen video, use argent-test-ui-flow, argent-qa-flows, or argent-screen-recording respectively.

Create an Argent flow

An Argent flow is a replayable sequence in .argent/flows/<name>.yaml.

For a saved QA test case, ticket, or acceptance criterion, load argent-qa-flows first. It adds deterministic setup, acceptance evidence, and two-pass proof.

Read the relevant reference

Before creating or changing a flow, read Live authoring completely.
When polishing, composing, or manually reviewing YAML, read Flow YAML. For Vega, read its platform limits before recording remote or keyboard tools.
Flows run on physical iPhones (an iOS list-devices entry with kind "device"), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as device (CLI --device), and only a connected phone can run. pinch/rotate steps fail there like the live tools. On hardware the flow tree is the describe tree: same ids and roles, no UIView hierarchy. See argent-ios-device-interact for the hardware contract.
On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read Reliability and recovery.

Non-negotiable rules

Record the first walkthrough. Start the recorder before the first launch or in-app action. Do not reconstruct a rehearsed path.
Record checks when their states appear. Record await-ui-element live, then convert it during polish. An echo records intent or diagnostic context, not app behavior or a verdict. A screenshot is human evidence, not an executable verdict. For absence, record the same selector as visible, perform the removing action, then record it as hidden.
Use semantic targets. Prefer a strict id, then stable text or an accessibility label. Use scroll-to for off-screen elements. Resolve every raw-point warning immediately through the coordinate fallback gate.
Prove every screen change. Record a destination-only identity check. During polish, follow it with await: { idle: true }. Stillness does not prove identity, and idle can pass with a warning.
Polish only executed behavior. Convert recorded steps without changing their meaning. Record any missing action or structural check live. The only unrecorded insertions are a planned snapshot:, a navigation await: { idle: true }, and the documented Chromium packaging launch:.
Use scripts only when the user requests them. Read Flow YAML: Local scripts, then record each script with flow-add-script.
Replay the final YAML end to end. A normal flow needs one uninterrupted full pass. argent-qa-flows requires two consecutive passes.

Stable selectors

A stable selector is fixed by app code and survives account, data, time, count, order, and every locale and environment the flow supports. Prefer ids such as settings-screen. Do not gate on values such as Today, Item 4, usernames, counters, or timestamps.

Flow-only selector scopes

During polish, use within, after, and next to disambiguate repeated elements. Read Flow YAML: Relational scopes for their frame-based semantics and failure cases.

Workflow

Choose the flow type:
- e2e: the first step that is not echo: or script: is launch:. The flow controls process start.
- fragment: there is no leading launch. Declare a precise executionPrerequisite.
Follow Live authoring: start, record one verified step at a time, finish, polish, audit, and replay.
Report the file, replay command, result, prerequisite or side effects, and every coordinate or raw-gesture exception.

Proactive recording

Before repeating three or more interactions, tell the user and start a recording. Record that run and replay it afterward. A completed path cannot be recorded retroactively.

Repair

When replay fails, follow Reliability and recovery. Inspect the first divergence, correct the smallest justified unit, audit, and replay the full flow. Stop after two unsuccessful correction cycles. Never weaken a requested check to obtain a pass.