Capability
plungeai-workflows
Build, validate, test, and save PlungeAI (Ocean Studio) workflows in CNL YAML.
Build, validate, test, and save PlungeAI (Ocean Studio) workflows in CNL YAML. Use when the user wants to create or edit a PlungeAI/Ocean workflow, orchestrate PlungeAI agents, write CNL YAML, run a multi-agent pipeline on PlungeAI, or turn research in this chat into a saved Studio workflow. Triggers: "PlungeAI workflow", "Ocean Studio workflow", "CNL", "build a workflow", "save this as a workflow", "plungeai agents".
Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)
Author CNL workflow YAML for the PlungeAI platform, prove it works, and save it so it appears in Ocean Studio and every connected app.
Prerequisites (check first, once)
- Preferred: the
plungeaiMCP server is connected (tools namedplungeai_*are available). Confirm identity withplungeai_whoami. - Otherwise: you can still author correct YAML and hand the user a paste-ready
block (see
references/channels.md, Channels 2-3).
The loop
- Understand the goal. One sentence: input → steps → deliverable. Ask only if the goal is genuinely ambiguous.
- Discover agents — never from memory.
plungeai_list_agents {search: "<capability in plain words>"}per capability. Take ids verbatim from results (kebab-case). Unknown or inactive ids are refused at execution. Fetch a full card with{agent_id}before using an unfamiliar agent — cards carry parameters and "Not for → use X instead" redirects. - Author the YAML. Load
references/cnl-spec.mdand pick a shape fromreferences/recipes.md. Independent steps go inparallel; chained steps insequentialwith{data:task_id}; goal-driven open-ended work is ONEtype: harnesstask, not many small tasks. Long prompts use block scalars (prompt: |) — never hard-wrap a value. - Test ad-hoc BEFORE saving.
plungeai_execute_workflow {workflow_yaml, input}(mode: "async"+plungeai_get_workflow_statusfor long runs). Read the actual output — does it satisfy the user's goal? Iterate the YAML, not the save. - Save.
plungeai_workflow {action: "create", name, yaml, description}. The platform re-validates server-side; a refusal lists field errors — fix exactly those and retry. On success it syncs live to Studio and peer apps. Iterations on a saved workflow:action: "update"(plus"save_version"before big changes). - Learn-back (offer it). If real research happened in this chat, offer:
plungeai_learn {source: "<distilled findings>"}to save it as a reusable platform skill that future runs can inject.
Hard rules (the top causes of refused YAML)
- Agent ids ONLY from a live
plungeai_list_agentssearch.brave-agent, neverbrave-search. - These do NOT exist:
$variable,depends_on,outputs:,parallel: true,schedule:(scheduling is configured in Studio, not YAML). parallel/sequential/batch/dynamic/debate/validateblocks never carryagent:— agents go on the inner tasks.type: taskreadsprompt:(orquery:) — not input/instructions/message.goal:belongs totype: harnessonly.- Every
idunique; data flows automatically — never hand-wire results. - Search agents (brave-agent, tavily-agent, …) take SEARCH TERMS — short
queries, not instructions. Synthesis, analysis, and "based on the research
above…" prompts belong on
llm-agent.
When something fails
- create refused → the message names field + problem; fix exactly that, retry once.
- "agent not active/unknown" → re-search the registry; the catalog is live.
- execution succeeded but output is wrong → improve prompts/structure and re-run ad-hoc; only save after the output is right.
- no MCP tools available → Channels 2-3 in
references/channels.md.
References (load on demand)
references/cnl-spec.md— full CNL v6 reference (all 10 task types, validation errors)references/recipes.md— canonical patterns + when to use eachreferences/channels.md— MCP (https://mcp.plungeai.com/v1) / Studio paste / raw HTTP APIexamples/*.yaml— six validated, runnable workflows
More
references/overview.md— the platform-level view: parallelism facts (measured, not guessed), placeholders and date tokens, execution/results/ follow-up semantics, failure semantics.references/api.md— the One API/v1/workflows/*HTTP surface: inline vs saved execution, SSE streaming events, result redemption, cancel, trace correlation, legacy aliases.references/mcp.md— the full MCP tool set for workflows:plungeai_execute_workflow,plungeai_get_workflow_status,plungeai_list_workflows,plungeai_workflow(CRUD + versioning),plungeai_build_workflow,plungeai_executions, andplungeai_templates(action: "use"— instantiating a gallery template as a workflow; browsing isplungeai-discovery's).
Reference pages
Run multi-agent CNL workflows: inline (send the workflow document in the request), saved (reference a workflow id saved in Ocean Studio), each with an…
Connect once (self-service ozk key from Dashboard → One API → Keys, https://dashboard.plungeai.com (opens in a new tab)):
CNL (Cognitive Natural Language) is PlungeAI's YAML workflow language: you declare tasks and how they compose (parallel, sequential, batch, debate, harness…
Workflows are CNL YAML run by the platform engine.
A workflow is a YAML document (CNL — Cognitive Natural Language) that the engine executes as a DAG of agent calls: parallel fan-out, sequential pipelines…
Full runnable versions live in examples/. Two composition rules apply to all of them:
Examples
01-simple-search.yaml
name: "Simple Single Task"
version: "2.0.0"
description: "Single search task — the smallest valid CNL workflow."
tasks:
- type: "task"
id: "single_task"
agent: brave-agent
prompt: "simple search test"
input: "electric vehicles 2026"02-parallel-research.yaml
name: "Parallel Research With Synthesis"
version: "2.0.0"
description: "Three parallel searches from different engines, then LLM synthesis. The most common production pattern."
tasks:
- type: "parallel"
id: "research_phase"
subtasks:
- type: "task"
id: "brave_search"
agent: brave-agent
prompt: "{input} — latest news, trends, and analysis"
- type: "task"
id: "tavily_research"
agent: tavily-agent
prompt: "{input} — cited sources and detailed reporting from the last 12 months"
- type: "task"
id: "exa_deep"
agent: exa-agent
operationType: "search"
prompt: "{input} — academic papers, institutional research, and expert analyses"
- type: "task"
id: "synthesis"
agent: llm-agent
prompt: |
Synthesize the parallel research into a comprehensive report on {input}.
Sources:
Brave: {data:brave_search}
Tavily: {data:tavily_research}
Exa: {data:exa_deep}
Identify common themes, contradictions, and the three strongest insights.
input: "quantum computing commercial applications"03-hierarchical.yaml
name: "3-Level Hierarchical Nesting"
version: "2.0.0"
description: "parallel → sequential → parallel nesting. Demonstrates unlimited nesting depth with data flowing automatically."
tasks:
- type: "parallel"
id: "level_1_parallel"
subtasks:
- type: "task"
id: "simple_task"
agent: brave-agent
prompt: "{input} — quick overview"
- type: "sequential"
id: "level_2_sequential"
subtasks:
- type: "task"
id: "deep_search"
agent: tavily-agent
prompt: "{input} — deep research with citations"
- type: "parallel"
id: "level_3_parallel"
subtasks:
- type: "task"
id: "business_angle"
agent: llm-agent
prompt: "From the research, extract business implications for {input}"
- type: "task"
id: "technical_angle"
agent: llm-agent
prompt: "From the research, extract technical implications for {input}"
- type: "task"
id: "final_report"
agent: llm-agent
prompt: "Combine all prior branches into a comprehensive report on {input}."
input: "autonomous vehicle regulation"04-validate-consensus.yaml
workflow:
name: "Consensus Validation With 3 Validators"
version: "2.0.0"
description: "Three LLM validators run in consensus on a single piece of content. Use when correctness must be triple-checked before publishing."
tasks:
- type: validate
id: fact_check
aggregation: consensus
validators:
- agent: llm-agent
validation_rule: "Check if the numerical claims are plausible and internally consistent"
- agent: llm-agent
validation_rule: "Check for logical consistency — identify any contradictions"
- agent: llm-agent
validation_rule: "Check completeness — are all key financial metrics covered"
success_criteria: "Content must be factually plausible, logically consistent, and comprehensive"
input: "Tesla reported Q4 2025 revenue of $25.7B. The automotive segment contributed $21.3B while energy generation and storage added $2.8B. Gross margins improved to 19.8% from 17.6% year-over-year. The company delivered 495,000 vehicles in Q4, a 12% increase from Q3."05-batch-items.yaml
name: "Per-Item Batch Pipeline"
version: "1.0.0"
description: "Run the same two-step pipeline for every item in a list, then roll up."
tasks:
- type: "batch"
id: "per_company"
items:
- "Cloudflare"
- "Vercel"
- "Fly.io"
tasks:
- type: "task"
id: "research"
agent: brave-agent
prompt: "{item} — company overview, funding, latest news"
- type: "task"
id: "brief"
agent: llm-agent
prompt: "From the research above, write a 5-bullet analyst brief on {item}"
- type: "task"
id: "rollup"
agent: llm-agent
prompt: "Combine the briefs into one comparison table: {data:per_company}"
input: "edge platforms"06-harness-mission.yaml
name: "Bounded Research Mission"
version: "1.0.0"
description: "A goal-driven harness run with an inline mission, effort preset, and turn cap."
tasks:
- type: "harness"
id: "market_scan"
goal: "Map the top 5 vendors for {input}, with pricing and one differentiator each."
mission:
mission: "You are a market analyst. Research thoroughly, cite sources, stay on topic."
effort: "standard"
max_turns: 12
success_criteria:
- "5 vendors named with pricing"
- "every claim has a source URL"
- type: "output"
id: "deliver"
format: "markdown"
input: "workflow orchestration platforms"