Workflows and Skills
Ship durable workflows that agents and the App start and follow as runs, and skills that each deploy publishes to a read-only collection users can copy.
An App can also ship workflows (scripts BotDojo runs step by step, with agent steps and pauses that wait for a person) and skills (instructions for agents, published with each deploy).
Preview
Names and options on this page can change before general availability.
Declare a workflow
Declare a workflow in botdojo.app.ts and permit it in a role by name, like a
function:
import { defineApp, defineWorkflow } from "@botdojo/app";
export const weeklyProjectDigest = defineWorkflow({
name: "weekly_project_digest",
description: "Summarize open projects and overdue tasks for the week.",
source: "workflows/weekly-digest.workflow.ts",
// Optional:
connections: { crm: ["search_contacts"] },
limits: { max_duration_ms: 20 * 60_000, max_subagents: 1, max_total_cost_usd: 1 },
});
export default defineApp({
// ...
roles: [{ key: "editor", label: "Editor", permits: { operations: ["weekly_project_digest"] } }],
workflows: [weeklyProjectDigest],
});
Workflow and function names share one namespace. Rename with
renamedFrom. A run that reaches
a limit stops with an error:
| Limit | Default | Maximum |
|---|---|---|
max_duration_ms | 30 minutes | 6 hours |
max_steps | 500 | 5,000 |
max_tool_calls | 1,000 | 10,000 |
max_subagents (agent steps; 0 for none) | 5 | 50 |
max_total_cost_usd | 5 | 100 |
Write the script
The script is plain TypeScript, cannot import modules, and exports
inputSchema, workflow, and optionally outputSchema and resultCard:
export const inputSchema = {
type: "object",
properties: { asOf: { type: "string", description: "YYYY-MM-DD" } },
additionalProperties: false,
};
export const outputSchema = {
type: "object",
properties: { openProjects: { type: "number" }, summary: { type: "string" } },
required: ["openProjects", "summary"],
};
export async function workflow(ctx) {
const projects = await ctx.step({ key: "open_projects_v1", label: "List open projects" }, () =>
ctx.tool("app://self", "list_projects", { where: [{ field: "phase", operator: "in", value: ["Intake", "Active"] }] }),
);
const digest = await ctx.agent({
key: "summarize_v1",
label: "Write the digest",
// The agent reads only the prompt.
prompt: `Summarize these projects in under 100 words:\n${JSON.stringify(projects.items)}`,
outputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
});
const approval = await ctx.halt("approve_v1", { message: "File this digest?", text: digest.output.text });
if (!approval.approved) return { openProjects: projects.items.length, summary: "Not filed." };
return { openProjects: projects.items.length, summary: digest.output.text };
}
export function resultCard(ctx) {
return `<p>${ctx.result.openProjects} open projects</p>`;
}
ctx.stepkeeps each step's result, so a resumed run skips finished steps.ctx.haltpauses the run until the person who started it answers.ctx.agenttakes an optionalmodel. It does not throw: on failure it returnsstatus: "error"with the reason inerror.
A run reaches only these, as the person who started it:
| Address | What it reaches |
|---|---|
app://self | The App's functions and table operations, with that person's roles. |
app://connections/<alias> | A declared connection, with that person's permission. Ask before the run starts. |
ctx.agent | That person's Workspace agent, or the agent the App runs as. |
Workflows run on BotDojo only: botdojo-app dev and botdojo-app test
check the files without running them.
Where runs live
A run never lives in the App's project. Run as, under Advanced in App settings, decides whose it is:
| Run as | The run lives in |
|---|---|
| The person using the App (the default) | That person's personal project |
| An agent identity | The agent's own project, for everyone who uses the App |
- With the default, a person must open their Workspace once before starting runs.
- Only an administrator of the agent's own project can choose that agent.
- Only the person who started a run can open, answer, or stop it. Project administrators of the App's project see each run's summary on the App's Activity tab.
Start and follow runs
On an App connection, each workflow the caller's roles permit is a
tool named
after it. Calling it starts a run and returns its run_id at once. Every
workflow shares these run tools:
| Tool | Does |
|---|---|
workflow_runs | Lists the runs you started. |
workflow_run_status | A run's status, steps, pending question, and result. |
workflow_run_wait | Waits until the run pauses or finishes, up to 50 seconds. |
workflow_run_resume | Answers a paused run. |
workflow_run_abort | Stops a run. |
workflow_run_read | Reads a stored file or a step's input or output. |
show_workflow_run | Shows live progress in the chat. |
Agents ask before starting, answering, or stopping a run unless an administrator allows those tools in the connection's settings.
The App's UI uses app.workflows, which also has list, runs, status,
and abort:
const handle = await app.workflows.start("weekly_project_digest", { asOf: "2026-11-11" });
let run = await app.workflows.wait(handle.run_id, { timeoutMs: 15000 });
if (run.status === "waiting") run = await app.workflows.resume(handle.run_id, { approved: true });
Ship skills
Put each skill in its own folder, such as skills/project-intake/SKILL.md,
and declare the folder:
defineApp({ /* ... */ skills: { dir: "skills" } });
SKILL.mdstarts with YAML frontmatter:name(the folder's name: lowercase letters, digits, and hyphens) anddescription.- Files are text only, at most 1 MB each and 200 per skill.
- Each deploy publishes the skills to the environment's read-only skills collection. If that fails, the deploy stands and the Skills tab can publish again.
- People use the collection as is, or choose Copy to my skills and edit the copy. Update brings in the App's later changes and keeps their edits.