| name | cortex-config |
| description | Interactively create a Cortex YAML config for multi-agent orchestration. Supports all three modes — workflow (DAG), mesh, and gossip. |
| argument-hint | ["optional output path"] |
| disable-model-invocation | false |
Cortex Config Skill
Create a Cortex YAML config from a short interactive conversation. Asks the user a few questions, designs the agent/team structure, shows a plan, then writes the file.
Step 1 — Choose mode
Ask the user which mode they want. Present all three with one-line descriptions:
- Workflow (DAG) — structured execution with team dependencies. Teams run in parallel tiers, upstream results feed downstream prompts. Best for multi-step projects with clear ordering.
- Mesh — autonomous agents with optional messaging. Each agent works independently, can see a roster of peers, and messages others only when needed. Best for parallel workstreams.
- Gossip — decentralized knowledge sharing. Agents explore a topic from different angles, findings are exchanged periodically via gossip protocol. Best for research and brainstorming.
If $ARGUMENTS contains a mode or enough context to infer one, skip this question.
Step 2 — Gather project details
Ask questions in a single round (use AskUserQuestion). Tailor questions to the chosen mode.
All modes
- Project name — what is this called?
- What are agents working on? — describe the objective in 2-3 sentences. The user MUST provide a real description — without it you cannot design meaningful agents. If the answer is too vague, ask follow-ups.
- Cluster context — any shared background all agents should know? (optional)
Mode-specific questions
Workflow (DAG):
4. How many teams? — suggest a number with names based on the description (e.g., "3 teams: backend, frontend, integration"). Include "auto" and custom options.
5. Model — sonnet (recommended), opus, or haiku
6. Permission mode — acceptEdits (recommended) or bypassPermissions
Mesh:
4. How many agents? — suggest specific agents with names and roles based on the description (e.g., "3 agents: market-sizing, competitor-analysis, product-strategy")
5. Model — sonnet (recommended), opus, or haiku
6. Permission mode — acceptEdits (recommended) or bypassPermissions
Gossip:
4. How many agents? — suggest specific agents with names and topics based on the description
5. Rounds — how many gossip exchange rounds? (suggest a default based on scope, typically 3-5)
6. Model — sonnet (recommended), opus, or haiku
Critical rule
Do NOT proceed to Step 3 until you have a concrete understanding of what the agents should accomplish. If the user gives a vague answer, ask follow-up questions. You need enough detail to write specific prompts — not generic boilerplate.
Step 3 — Design the config
From the user's answers, design the full config.
Workflow (DAG) design
- Name each team after its domain (e.g.,
backend, frontend, data-pipeline)
- Each team gets a
lead with a descriptive role
- Add
members with distinct roles and focus areas (2-5 per team)
- Write a rich
context block per team
- Determine DAG dependencies — no circular deps allowed
- Design 4-7 tasks per team with
summary, details, deliverables, and verify
Mesh design
- Name each agent after its domain (e.g.,
market-sizing, competitor-analysis)
- Give each agent a specific
role (one-line description of what they are)
- Write a detailed
prompt for each agent — what they should research/build/analyze, what deliverables to produce, and how to structure their output
- Set mesh settings (heartbeat/suspect/dead timeouts — defaults are usually fine)
Gossip design
- Name each agent after its exploration angle (e.g.,
competitor-analyst, market-sizer)
- Give each agent a
topic and detailed prompt
- Set gossip settings (rounds, topology, exchange interval)
- Add seed knowledge if relevant
Step 4 — Present the plan
Show a formatted summary for user review. Format depends on mode:
Workflow plan
## Cortex Config: <name>
Mode: workflow (DAG)
### Defaults
model: <model> | max_turns: <N> | timeout: <N>min | permission: <mode>
### Execution Tiers
**Tier 0** (parallel):
- <team>: <lead role> + <N members>
**Tier 1** (depends on: <tier 0 teams>):
- <team>: <lead role> + <N members>
### Output
<filename>.yaml
Mesh plan
## Cortex Config: <name>
Mode: mesh
### Defaults
model: <model> | max_turns: <N> | timeout: <N>min | permission: <mode>
### Agents
- <name>: <role>
- <name>: <role>
### Mesh Settings
heartbeat: <N>s | suspect timeout: <N>s | dead timeout: <N>s
### Output
<filename>.yaml
Gossip plan
## Cortex Config: <name>
Mode: gossip
### Defaults
model: <model> | max_turns: <N> | timeout: <N>min
### Agents
- <name>: <topic>
- <name>: <topic>
### Gossip Settings
rounds: <N> | topology: <type> | interval: <N>s
### Output
<filename>.yaml
Ask: "Does this look right? I'll write the config."
Step 5 — Write the YAML
Write the file to the output path from $ARGUMENTS, or default to examples/<project-name>.yaml inside the cortex directory.
Workflow schema
name: "<project name>"
defaults:
model: <model>
max_turns: <number>
permission_mode: <mode>
timeout_minutes: <number>
teams:
- name: <team-name>
lead:
role: "<role description>"
members:
- role: "<member role>"
focus: "<what this member owns>"
context: |
<rich domain context>
depends_on:
- <team-name>
tasks:
- summary: "<short description>"
details: "<specific requirements>"
deliverables:
- "<file path>"
verify: "<shell command>"
Mesh schema
name: "<project name>"
mode: mesh
cluster_context: |
<shared context for all agents>
defaults:
model: <model>
max_turns: <number>
permission_mode: <mode>
timeout_minutes: <number>
mesh:
heartbeat_interval_seconds: 30
suspect_timeout_seconds: 90
dead_timeout_seconds: 180
agents:
- name: <agent-name>
role: "<one-line role description>"
prompt: |
<detailed assignment — what to do, what deliverables to produce,
how to structure output. Be specific.>
Gossip schema
name: "<project name>"
mode: gossip
cluster_context: |
<shared context for all agents>
defaults:
model: <model>
max_turns: <number>
permission_mode: <mode>
timeout_minutes: <number>
gossip:
rounds: <number>
topology: <full_mesh|ring|random>
exchange_interval_seconds: <number>
agents:
- name: <agent-name>
topic: "<knowledge topic>"
prompt: |
<detailed exploration instructions>
seed_knowledge:
- topic: "<topic>"
content: "<starting knowledge>"
Quality checklist before writing
- Project name is non-empty
- Every agent/team has a name
- No duplicate names
- Agent prompts are specific and actionable (not generic filler like "do research")
- Workflow: all
depends_on references exist, no circular deps, every team has tasks
- Gossip: rounds >= 1, valid topology
- Mesh: positive timeout values
Step 6 — Print next steps
After writing the file, print mode-appropriate next steps:
Workflow
<filename> written!
Next steps:
1. Review: cat <filename>
2. Dry run: mix cortex.run <filename> --dry-run
3. Run: mix cortex.run <filename>
Mesh
<filename> written!
Next steps:
1. Review: cat <filename>
2. Dry run: mix cortex.run <filename> --dry-run
3. Run: mix cortex.run <filename>
Gossip
<filename> written!
Next steps:
1. Review: cat <filename>
2. Dry run: mix cortex.run <filename> --dry-run
3. Run: mix cortex.run <filename>
