Skip to main content
Use this when you want to change Yukta by describing the change instead of writing JSON or calling REST. Each recipe below is a prompt to type, plus what happens behind it: a handful of prompts, usually one to four, and the assistant makes the tool calls. Prerequisites: Connect an assistant done, with the skill installed. Tool names and arguments here come from the server’s MCP tools, listed in the MCP tools reference. The prompts are examples. Rephrase them freely; what matters is that you name the session, the workflow and the outcome. The assistant’s own wording will differ, and so may the order of some read calls.

The three-step habit

Every recipe follows the same shape.
  1. Ask. Describe the result and say “show me before you apply it”.
  2. Review. Read the JSON or the plan the assistant shows. Ask it to explain anything you do not follow.
  3. Apply. Say yes. Then check the result with a different client, such as yukta-cli, as each recipe suggests.

Which role each recipe needs

whoami tells the assistant its role. A call the role does not allow is refused with HTTP 403, and the assistant should tell you which role it needs instead of trying.

1. Create a workflow from a description

Prompt:
Tools, in order: whoami, get_session_creation_instructions, list_plugins, get_plugin_details (once per node type it is unsure about), list_sessions (to see whether the id exists), create_session, then start_workflow and get_workflow_status or get_execution_result if you ask it to run the workflow. Check: the node types, the condition coverage >= 80, no keys or passwords in the JSON, and the warnings field of the create_session answer. Then compare with yukta-cli workflow history release-checks after a run. Role: ADMIN to create, OPERATOR to start. This is the walk-through in Let an assistant build a workflow.

2. Change one node

Prompt:
Tools, in order: get_workflow_details (the current definition), then create_session with the changed session. There is no tool that edits a single node: create_session replaces the whole session, so the assistant sends the full session with one node changed. It can show you the difference first, and after the save diff_workflow_versions shows what changed. Check: that only the node you named changed. Ask the assistant to list list_workflow_versions and diff_workflow_versions for gate after the save. Role: ADMIN. The assistant must ask before it replaces the session (see Review before you approve).

3. Add a retry or a branch

Prompt:
Tools, in order: get_workflow_details, get_plugin_details for the node involved, then create_session. A retry is an engine.retry object on the node (maxAttempts, backoffMs) with onError set to ROUTE and an edge from the error port. For a branch, the same: it adds a BRANCH node and edges, and shows you the new graph. Check: the new edges and the port each one leaves through. Read the Loop and retry and Route and branch guides if a port name is unfamiliar. Role: ADMIN.

4. Validate and roll back a bad edit

Prompt, to look:
Tools, in order: list_workflow_versions, diff_workflow_versions (with olderVersion, and newerVersion left out to compare with the current definition). Prompt, to undo:
Tools, in order: list_workflow_versions, rollback_workflow (with version), note_workflow_version. Check: yukta-cli session workflow versions release-checks gate shows the restored definition as a new version on top. Runs that already started keep the version they use. A workflow keeps its newest 20 versions. Role: VIEWER to list and diff, OPERATOR to roll back or add a note. Validation itself happens when you save: create_session checks the session and returns warnings, and the assistant should act on them before it starts a run.

5. Schedule it

Prompt:
Tools, in order: get_plugin_details with SCHEDULE_TRIGGER, get_workflow_details, create_session, then start_workflow. Check: the trigger has exactly one of intervalMs and cron, and timeoutSeconds is longer than the gap between ticks. A schedule lives inside one long-running run and does not survive a server restart; a good assistant says so. See Schedule a workflow. Role: ADMIN to save, OPERATOR to start.

6. Add a failure-guard supervisor

Prompt:
Tools, in order: list_supervisor_presets (type rules), get_supervisor_engine (type rules, for the settings shape), save_supervisor (type rules, id, settings, dryRun true), check_assignment (read only), then, after your yes, set_assignments with [{"target":"session:release-checks"}]. Check: get_supervisor shows dryRun true, the rules and the assignment. The guide asks you to name the commands the supervisor may send in allowedCommands (here PauseWorkflowCommand), so check that the settings contain it. Dry run means its commands are only recorded; read them with yukta-cli supervisors decisions --supervisor release-guard, which lists outcomes such as dry-run. Role: ADMIN. set_assignments takes direct control of the unit away from people unless the supervisor lists the command in operatorAccess, so the assistant must ask first. See Write a rules supervisor and Assign a supervisor.

7. Give a supervisor a parent, or build a reporting chain

Prompt:
Tools, in order: get_supervisor_engine, save_supervisor for policy, check_assignment and set_assignments (target global), get_supervisor for release-guard to read its parents. The catch: the MCP save_supervisor tool has no parents or delegation argument, and it creates the supervisor without parents. The assistant cannot set a parent over MCP. It runs the CLI command for you, or hands it to you:
PUT /api/supervisors/release-guard with a parents list does the same over REST. Run it after any later save_supervisor of the child, and confirm with get_supervisor that parents still lists policy. Check: get_supervisor for release-guard shows policy under parents. A supervisor cannot be its own ancestor and a chain has at most four levels. See Build a hierarchy. Role: ADMIN.

8. Assign or move ownership, and handle OWNERSHIP_CONFLICT

Prompt:
Tools, in order: get_ownership (sessionId, workflowId), check_assignment, then, after your yes, set_assignments for the new owner. To remove it from the old owner, the assistant sends that supervisor’s remaining targets (an empty list owns nothing) with set_assignments. Check: one unit has one owner. A target another supervisor owns is refused with OWNERSHIP_CONFLICT and nothing changes: every check passes or none is applied. Read the owner named in the refusal, then either change the other supervisor’s assignments first or pick a different target. A locked assignment changes only with unlock true, by a lock holder. get_ownership and get_supervision confirm the result. Role: ADMIN.

9. Replay a supervisor before you enable it

Prompt:
Tools, in order: get_workflow_history (to pick a run), replay_supervisor (supervisorId, executionId), then replay_supervisor again with settings set to the draft. For a rules supervisor, get_rules and replay_rules with a rules draft do the same on the rules document alone. Check: each decision has command, executionId, cause, reason and allowed. An empty list means the supervisor would have done nothing. A replay rebuilds only the status events of the run, so a rule that depends on log lines or node metadata will not fire in a replay even if it would live. Nothing is sent to any run. See Replay a supervisor. Role: ADMIN.

9b. Route approvals to an agent, keep HIGH risk with people

Prompt:
Tools, in order: list_pending_inputs (to see the requests that exist), list_supervisor_engines and get_supervisor_engine for the http engine, save_supervisor for the agent supervisor. The split: who is asked, in which order, is a route in server configuration (yukta.input.routes.*), not an MCP tool. The assistant proposes the YAML and you apply it; a restart is needed. The risk rule is enforced by the server, not by the route or the prompt: an agent can never answer a request of HIGH risk, whatever the assistant sets up. See Route input requests and Who decides. Check: list_pending_inputs shows each request with its risk, tier and deadline. Answering stays your call: the skill tells the assistant never to send approve or reject with answer_input without your yes. Role: ADMIN to save the supervisor; VIEWER to list requests.

10. Create an agent credential

Prompt:
Tools, in order: get_supervisor_engine (type http), save_supervisor (dryRun true), check_assignment, set_assignments. The credential: create_credential (supervisorId, optional ttlHours) exists and issues the token once, but the token then passes through the assistant’s context. The skill prefers that you make it in the UI or CLI, so ask for the command:
Check: yukta-cli supervisors credential show triage-agent shows when it was issued and last used, never the secret. An agent holding the token works only on /api/agent/v1, and no person’s API key works there. See Write an agent supervisor. Role: ADMIN.

Review before you approve

An assistant is fast, and a fast mistake is still a mistake. Four habits keep you in charge. Know what it will ask you about. The yukta-workflows skill tells the assistant to stop and get an explicit yes, naming what will happen, before it does any of these:
  • create_session when the session id already exists: it replaces that session. A new session is also code that runs on the server.
  • delete_session, delete_workflow, and any call with force set, which cancels active runs.
  • control_workflow with STOP_ALL, and any stop with mode KILL or CANCEL.
  • rollback_workflow and set_scheduler_limits.
  • answer_input with approve or reject: that is your decision, never the assistant’s.
Supervisor changes (save_supervisor, set_assignments, delete_supervisor, rollback_supervisor, create_credential, revoke_credential) also need your yes, according to the skill. A skill is good manners, not a lock; the role on the key is the lock. Dry run first. Save a new supervisor with dryRun true, and use replay_supervisor on a past run before you turn it on. Dry run records what it would have done and sends nothing. When you have read the decisions and agree, ask the assistant to save the supervisor again with dryRun false. Give the key the least role that works. VIEWER to look and explain, OPERATOR to start and steer, ADMIN only for the moment you want it to write, ideally with a separate key. A key can also be limited to sessions. Ask it to explain before it applies. “What will this change, what could go wrong, and how do I undo it?” is a good last prompt before every yes. The answer should name rollback_workflow or rollback_supervisor as the undo.
Text the assistant reads from runs, logs or input requests is data that someone else wrote, not instructions. If the assistant proposes a change because a log line told it to, stop and ask why.

Verify it worked

For any recipe, check the result with a client the assistant did not use:
The supervisor you saved appears with its settings, the decisions show outcomes such as dry-run, and the history shows the runs the assistant started.