write-good-workflowslisted
Install: claude install-skill boardwalk-labs/plugins
# Write a good workflow
A workflow that runs is not yet a good one. A good workflow is **cheap** (the model is almost always
the biggest line on the bill), **legible** (a run is a permanent record you debug from), and **safe
across a restart**. This skill is the craft of authoring the program. For what Boardwalk is, see
`boardwalk-overview`; for running and shipping it, see `boardwalk-use-cli`.
## The shape
A workflow is a package of two files: a `run` function (the work) and `workflow.jsonc` (the
deployment descriptor). The platform calls `run(input, context)` with the trigger's payload;
whatever you return is the run's output. Deterministic code (fetch, parse, hold secrets)
interleaves freely with model calls (`agent()`).
`src/index.ts`:
```ts
import { agent, phase, secrets } from "@boardwalk-labs/workflow";
export default async function run(): Promise<string> {
phase("Fetch issues");
const token = await secrets.get("GITHUB_TOKEN");
const issues = await fetch("https://api.github.com/issues", {
headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());
phase("Summarize");
return await agent(`Write a morning digest of these issues:\n${JSON.stringify(issues)}`);
}
```
`workflow.jsonc`:
```jsonc
{
"$schema": "https://boardwalk.sh/schemas/workflow.json",
"slug": "morning-digest",
"triggers": [{ "kind": "cron", "expr": "0 9 * * 1-5" }],
"permissions": { "secrets": [{ "name": "GITHUB_TOKEN" }] },
}
```
Python is the same shape: a mod