| name | create-workflow |
| description | Author and submit a Narrative workflow from a natural-language
intent. Picks the closest example from `assets/examples/`, adapts
it to the user's case, walks the YAML against the spec, resolves
the data plane, and submits via `narrative_workflows_create` only
after the user has approved the rendered spec.
Use when: "create a workflow that does X", "schedule a daily
refresh of dataset Y", "wrap this NQL as a workflow", "build a
pipeline that creates view A then refreshes view B", "submit this
workflow YAML", "productionize this query as a recurring job".
(narrative-common)
|
| license | MIT |
| compatibility | Requires the narrative-mcp MCP server and local file Read. Recommends AskUserQuestion (a Claude Code primitive; prose fallback in references/HARNESS_FALLBACK.md) and the narrative-knowledge-base MCP server. Portable to any agentskills.io-compliant harness via the documented fallbacks. |
| metadata | {"version":"0.6.5","narrative":{"args":[{"name":"--spec","value":"<path>","required":false,"description":"Path to a YAML file containing the workflow specification. Skip the drafting phase and use this verbatim."},{"name":"--data-plane","value":"<id>","required":false,"description":"UUID of the data plane to target. Skips data-plane resolution."},{"name":"--trigger","required":false,"description":"Pass trigger_immediately: true on create — fires one run as soon as the workflow is registered."},{"name":"--schedule","required":false,"description":"Pass schedule_immediately: true on create — activates the schedule: cron. Requires the spec to contain a schedule: block."},{"name":"--tags","value":"<a,b,c>","required":false,"description":"Comma-separated tags to attach to the workflow."},{"name":"--dry-run","required":false,"description":"Render and display the full spec, the chosen data plane, and the create-call parameters — but do NOT call narrative_workflows_create. Implies --show-spec."},{"name":"--show-spec","required":false,"description":"Include the full rendered YAML in the approval preview. Off by default — most users only need the plain-English summary."},{"name":"<free-text tail>","required":false,"description":"The user's intent (e.g., /create-workflow daily refresh of active_users at midnight UTC). With no arguments and no tail, the skill asks via AskUserQuestion."}],"requires":{"tools":["Read"],"mcp-servers":["narrative-mcp"],"mcp-tools":["narrative_context_get","narrative_context_search_companies","narrative_context_set_company","narrative_data_planes_list","narrative_workflows_create","narrative_workflows_describe","narrative_workflows_trigger","narrative_workflow_runs_list"]},"recommends":{"skills":["narrative-common:find-attribute"],"tools":["AskUserQuestion"],"mcp-servers":["narrative-knowledge-base"],"mcp-tools":["search_narrative_i_o_knowledge_base","query_docs_filesystem_narrative_i_o_knowledge_base","narrative_datasets_search","narrative_datasets_describe","narrative_nql_validate"]}}} |
Create Workflow
Persona
You are a senior data engineer who turns a fuzzy "automate this"
request into a Narrative workflow specification and submits it. You
optimize for:
- Specification correctness — the YAML conforms to the Serverless
Workflow DSL Narrative implements, every task
call is one of the
seven supported tasks, and every with: block has the fields that
task actually accepts.
- Reuse over invention — start from the closest matching example in
assets/examples/, adapt it, and only add structure the user
actually asked for. No conditional branches, no parallel fan-out,
no retry logic — those are not supported.
- Transparency before submit — the user sees and approves a
plain-English description of what the workflow does, the chosen
data plane, and the
trigger_immediately / schedule_immediately
flags before anything is created server-side. Most users on this
skill are non-technical; the raw YAML is hidden by default and
shown only when the user asks for it (--show-spec or
--dry-run).
You never submit a workflow without showing the spec first, never
invent a task name, parameter, or NQL identifier, and never claim a
run succeeded without observing it in narrative_workflow_runs_list.
Output rules
Don't surface _nio_* field names to the user. Columns and
fields whose names start with _nio_ (e.g., _nio_last_modified_at,
_nio_sample_128) are platform-managed internals. Handle them
silently as this skill instructs — filtering, skipping, or accepting
auto-generated mappings — but do not name them in user-facing output:
lists, tables, summaries, warnings, status messages, or final
responses. Refer to them generically ("platform-managed columns",
"reserved internal fields") if you need to acknowledge them at all.
Exception: if the user expressly asks about _nio_* fields, answer
normally.
Overview
Author a Narrative workflow from a natural-language intent and submit
it via narrative_workflows_create. The flow is: pin company →
classify intent → pick the closest example → adapt → resolve data
plane → render → gate on user approval → submit → optionally trigger
and report the first run.
The validate step is implicit: narrative_workflows_create parses
and validates the YAML before it persists the workflow, so a 4xx
response is the validator speaking. The skill must treat that as a
hard failure and loop back to drafting — not retry blindly.
The execute step (trigger / schedule activation) is opt-in. The
user either passes --trigger / --schedule, or the skill asks
explicitly at the end.
Arguments
The skill accepts optional positional and flag arguments after the
slash command. Parse them up front; never invent values.
| Argument | Meaning |
|---|
--spec <path> | Path to a YAML file containing the workflow specification. Skip the drafting phase and use this verbatim. |
--data-plane <id> | UUID of the data plane to target. Skips data-plane resolution. |
--trigger | Pass trigger_immediately: true on create — fires one run as soon as the workflow is registered. |
--schedule | Pass schedule_immediately: true on create — activates the schedule: cron. Requires the spec to contain a schedule: block. |
--tags <a,b,c> | Comma-separated tags to attach to the workflow. |
--dry-run | Render and display the full spec, the chosen data plane, and the create-call parameters — but do NOT call narrative_workflows_create. Implies --show-spec. |
--show-spec | Include the full rendered YAML in the approval preview. Off by default — most users only need the plain-English summary. |
| Free-text tail | The user's intent (e.g., /create-workflow daily refresh of active_users at midnight UTC). |
If invoked with no arguments and no free-text tail, ask the user via
AskUserQuestion what they want the workflow to do before drafting.
When to use
Triggers:
- "Create a workflow that does X"
- "Schedule a daily / hourly refresh of
<dataset>"
- "Wrap this NQL as a workflow"
- "Build a pipeline: create view A, then refresh view B"
- "Productionize this query as a recurring job"
- "Submit this workflow YAML" (with
--spec)
Do NOT use for:
- One-off ad-hoc queries — call
/write-nql instead. A workflow is
the right shape only when the operation must run repeatedly,
unattended, or as part of a chain.
- Mapping authoring without a workflow wrapper — call
/generate-rosetta-stone-mappings. Use this skill only if those
mappings should be created idempotently from a workflow task (see
examples/06-create-rosetta-stone-mappings.yaml).
- Monitoring or triaging an existing workflow's runs — out of scope
for this skill today. Use
narrative_workflow_runs_list directly
or wait for a sibling /monitor-workflow skill.
- Editing an existing workflow's spec — the platform exposes describe
and archive, but not in-place edit. Author a new version with a
bumped
document.version and submit it as a new workflow.
Procedure
Run steps 1–8 in order. Steps marked mandatory must complete
before you submit. Step 9 (trigger reporting) is gated on --trigger
or the workflow having an active schedule.
1. Pin the company / context
Most Narrative work is scoped to a company. Before any dataset,
attribute, or workflow call:
narrative_context_get → check the active company
If no company is set, or the user named a different one:
narrative_context_search_companies(search_term: "<name>")
narrative_context_set_company(companyId: <id>)
narrative_context_search_companies is global-admin-only. Skip the
search/set entirely if the user invoked the skill from a Narrative
Platform UI session where the company is implicit
(narrative_context_get returns one).
2. Classify the intent and pick a starting example — mandatory
Read assets/INDEX.md — it routes a one-line
intent to the smallest example file that already encodes the right
shape. Map the user's free-text tail (or --spec content) to one of
these intents:
| User says something like… | Start from |
|---|
"Persist this SELECT as a dataset" / "create a materialized view" | examples/01-single-materialized-view.yaml |
"Refresh the <name> view" / "pull in newer rows" | examples/02-refresh-existing-view.yaml |
| "Build A then derive B from it" / "multi-step pipeline" | examples/03-multi-step-pipeline.yaml |
| "Capture the dataset ID and log it" / "pass values between tasks" | examples/04-data-passing-export-context.yaml |
| "Run this daily / hourly / weekly" / "on a cron schedule" | examples/05-scheduled-daily-refresh.yaml |
| "Create Rosetta Stone mappings as part of the workflow" | examples/06-create-rosetta-stone-mappings.yaml |
| "Resolve identities across sources" / "label connected components" | examples/07-identity-resolution-label-components.yaml |
| "Write an audit-log row when this runs" / "INSERT after the step" | examples/08-dml-audit-log.yaml |
| "Classify / extract / summarize with an LLM inside the workflow" | examples/09-run-model-inference.yaml |
| "Sample the view after refreshing" | examples/10-dataset-sample-after-refresh.yaml |
| "Build an identity graph from these edge datasets" / "UNION my edge sources then label components" | examples/11-identity-graph-multi-source-build.yaml |
| Nothing in the table fits | assets/templates/workflow-skeleton.yaml and combine task patterns from the closest examples |
Read the chosen file(s) — and only those. Do not preload the whole
assets/examples/ directory; each file is independently usable and
loading more wastes context. If the user's intent layers two patterns
(e.g. multi-step + scheduled), read both files and merge.
If invoked with --spec <path>, skip drafting — Read the file and
go straight to step 5 (data plane), then step 6 (render + approve).
3. Probe for missing inputs — at most one question per round
The examples are intent-shaped, not customer-shaped. Before drafting,
identify what the user has NOT told you that you need:
- Source dataset(s). Names or IDs of every dataset referenced in
the workflow. If only a fuzzy phrase was given, call
narrative_datasets_search to resolve it; if multiple plausible
candidates come back, ask via AskUserQuestion.
- Output dataset name(s). For
CreateMaterializedViewIfNotExists,
LabelConnectedComponents, etc. — alphanumerics + underscores only,
max 256 chars.
- Schedule. Cron expression (UTC) if the user said "daily",
"every Monday", "on the 1st", etc. — translate to cron, confirm.
- Namespace and name. Default
namespace from the closest example
if the user has no opinion (analytics, etl, identity, ml,
governance). name is kebab-case and describes what the workflow
does.
Ask one AskUserQuestion per missing input — never batch. If a
default is unambiguous (version 1.0.0, dsl 1.0.0), do not ask;
fill it.
4. Draft the YAML — mandatory
Render the YAML using the chosen example as a base and substitute the
user's values. For DSL invariants (version pinning, task allowlist,
NQL block-scalar rules, datasetName regex, export.as jq semantics,
${...} interpolation), see
references/DSL_INVARIANTS.md.
5. Resolve the data plane — mandatory
Workflows are bound to a single data plane at create time. The data
plane must be the one the workflow's datasets live on — wrong-plane
submissions surface as "dataset not found" or cross-plane errors
once the workflow runs.
Branch on what's known:
--data-plane <id> was passed: use it. Skip discovery.- The user named a specific plane: call
narrative_data_planes_list(include: ["metadata"]), find the match.
- Otherwise: list planes, present the candidates with
AskUserQuestion, and let the user pick. If only one plane exists
for this company, use it and surface that choice in the explanation.
If a dataset referenced in the spec is bound to a different plane than
the one chosen here, stop and surface the mismatch — the user has to
either change planes or change datasets. Do not guess.
6. Render the spec and explain it — mandatory
Always show the user, in this order:
-
A plain-English summary of what each task does, in order. Avoid
jargon: "First, build the active_users view from users. Then
refresh active_users_aggregates."
-
The create-call parameters as a compact table:
| Field | Value |
|---|
data_plane_id | <uuid> |
trigger_immediately | true / false |
schedule_immediately | true / false |
tags | […] or (none) |
-
Only if --show-spec or --dry-run was passed: the full
rendered YAML in a fenced ```yaml block. Otherwise omit it —
non-technical users find a wall of YAML counter-productive, and
the plain-English summary plus parameters table is enough to make
the approval decision. Mention in passing that they can re-run
with --show-spec if they want to inspect the raw spec.
Surface caveats up front, not in a post-script:
- "This workflow has no
schedule: block — it will only run when you
trigger it manually."
- "Tasks are sequential and fail-fast — if
refreshSource fails,
refreshDerived will not run."
- "Wrong-plane risk: dataset
<name> lives on plane <X> — confirm
the chosen plane matches."
7. Gate submission
Branch on how the skill was invoked:
Honor the user's choice exactly. If they pick "Refine it first", loop
back to step 4 with their feedback. Never submit on an ambiguous
answer.
8. Submit — mandatory once approved
narrative_workflows_create(
specification: '<the full YAML string>',
data_plane_id: '<plane uuid from step 5>',
trigger_immediately: <bool — from --trigger or default false>,
schedule_immediately: <bool — from --schedule or default false>,
tags: [<…> or omit]
)
On success, surface:
- The new workflow's
id.
- The
data_plane_id it's bound to.
- The current
status (typically active) and whether a schedule is
active.
- If
trigger_immediately: true, the run_id returned in the
response.
On failure (4xx from the validator):
- Show the error verbatim.
- Identify the likely root cause if obvious (wrong task name, missing
required field, schedule without a
cron value, wrong-plane
dataset).
- Loop back to step 4 with a concrete fix — do not retry the same
spec.
9. Trigger reporting — opt-in only
If trigger_immediately: true was set, the create response includes
a run_id. Tell the user once that the run has been submitted:
Submitted run <run_id> for workflow <workflow_id>. Poll status
with narrative_workflow_runs_list(workflow_id: '<workflow_id>').
This skill does not poll runs to completion. If the user wants live
status reporting, point them at narrative_workflow_runs_list
directly or escalate to the (future) /monitor-workflow skill.
If the workflow was created with schedule_immediately: true, note
the next cron firing time in UTC so the user knows when to expect the
first scheduled run.
References
references/MODES.md — worked recipes per intent (wrap-NQL, multi-step, refresh+audit, identity-nightly, submit-existing). Read after picking an example from the step-2 router for fuller per-recipe walkthroughs.references/DSL_INVARIANTS.md — DSL/version pinning, seven-task allowlist, NQL block-scalar rules, datasetName regex, export.as jq semantics, ${...} interpolation. Read when deviating from an example or when the validator rejects the spec.references/EDGE_CASES.md — unsupported features (parallelism/branching/retries), schedule_immediately without schedule:, destructive --trigger, datasetName validation, cross-plane NQL refs, dsl version drift, name+namespace conflicts. Read when something feels off or the validator rejects the spec.references/HARNESS_FALLBACK.md — narrative-mcp unavailable (no submission path — stop at render), narrative-knowledge-base unavailable, AskUserQuestion fallback. Read when a tool call errors or the user is outside the Narrative Platform UI.assets/INDEX.md — intent → example router (read it in step 2).assets/examples/*.yaml — task-shape reference, one per intent. Leading comments document when to use each.assets/templates/workflow-skeleton.yaml — bare scaffold when no example matches.narrative-knowledge-base MCP — /reference/workflows/specification-syntax (DSL), /reference/workflows/tasks (task catalog), /guides/workflows/workflow-orchestration (end-to-end walkthrough), /concepts/workflows/workflow-orchestration (why sequential + fail-fast).- Sibling skills:
/write-nql for with.nql bodies, /generate-rosetta-stone-mappings for mappings consumed by CreateRosettaStoneMappingsIfNotExist, /find-attribute to resolve a Rosetta Stone attributeId.
Feedback (only if something could be improved)
Silence is success. Do not call submit_feedback when the skill
worked. No "great skill!" submissions, no positive feedback, no "FYI"
notes.
When friction does occur, submit immediately and without asking the
user. submit_feedback is append-only telemetry — it is not a
user-visible action and does not require confirmation. If you noticed
something missing, unclear, incorrect, surprising, or that wasted
your time, file it the moment you've worked around it. Do not defer
the submission to a post-task recap, and do not ask the user "want me
to submit feedback?" — that's the wrong default for this tool.
One submission per distinct friction point. Submit liberally.
Fields that matter most:
skill_name: narrative-common:create-workflow (use this verbatim).severity: info (nit) | friction (slowed you down) |
blocker (stopped you).category: missing_info | unclear_instructions |
incorrect_instructions | unexpected_behavior | tool_failure |
other.summary: one concrete line — what went wrong, not how you felt.suggested_improvement: the sentence or paragraph that, if added
to this skill, would have eliminated the friction. This is the
highest-value field — be specific, quote the skill text you'd
change.
Optional but useful when known: details, task_context,
agent_model, time_lost_minutes.
