Integrating agents into your workflow: workflow docs, skills, evals, and who orchestrates

Prompting an agent by hand works until you need the same task done the same way twice. One-off prompts are not reviewable, the quality swings with how you phrased it that day, and there is no way to hand "how we do X" to a teammate or to another agent. The fix is to write the process down as a workflow, build it out of reusable skills, check it with evals, and put something in charge of running it.

Three layers#

Keep the layers separate. A skill should not know which workflow called it. A workflow should not contain orchestration logic. The orchestrator should dispatch, not do the work itself.

Writing a workflow document#

A workflow lives in the repo as a markdown file, version controlled next to the code it touches (a workflows/ folder works). It is written for a person to read and for an agent to follow. Anatomy:

• Name and when to use it. One line each. If the trigger is fuzzy the orchestrator will pick the wrong one.
• Inputs and preconditions. What must be true or provided before step 1.
• Steps. Numbered, each with an action, the skill it uses, the expected output, and a checkpoint. Write them as checkboxes so progress is visible.
• Guardrails. Hard "never" rules and "stop and ask if" conditions. These are the most important part and the most often skipped.
• Definition of done. The concrete artifacts that must exist: a passing test file, a changelog entry, a migration, a green pipeline.
• Outputs. What the workflow leaves behind for the next person.

# Workflow: Add an API endpoint

**When to use:** a new REST endpoint is needed on the core service.
**Inputs:** the route path, method, request/response shape, auth requirement.
**Preconditions:** an open ticket, a green main branch.

## Steps
- [ ] 1. Draft the contract. Skill: `api-contract`. Output: an OpenAPI fragment
      in `docs/api/`, reviewed against existing naming.
- [ ] 2. Add the handler + validation. Skill: `endpoint-handler`. Output: a diff
      limited to `src/api/` and `src/schemas/`.
- [ ] 3. Tests. Skill: `api-tests`. Output: happy path, auth failure, validation
      failure, one edge case. Must pass.
- [ ] 4. Wire auth + rate limit. Skill: `endpoint-security`.
      Checkpoint: HUMAN APPROVAL required before continuing.
- [ ] 5. Changelog. Skill: `changelog-entry`. Output: one entry in the required
      format.
- [ ] 6. Open the PR. Output: PR description links the ticket and the OpenAPI diff.

## Guardrails
- NEVER change an existing endpoint's response shape in this workflow.
- NEVER touch `src/billing/` or `src/auth/core/`.
- STOP AND ASK if the new endpoint needs a new database table.

## Done when
- Steps 1-6 checked, tests green, changelog entry present, PR open, CI passing.

Skills: the reusable unit#

A skill is a small instruction set for one capability. "Write a migration." "Add a feature flag." "Run the a11y audit and file the findings." Workflows reference skills by name, and one skill can serve many workflows.

• Keep them small. If a skill has phases and checkpoints, it is a workflow wearing a skill costume.
• Keep them context-free. A skill takes inputs and produces an output. It does not know what called it.
• Make them composable. "changelog-entry" is used by every workflow that ships something.
• Store them where the orchestrator can discover them by name, versioned alongside the workflows.

Evals: proving the workflow was respected#

Without a check, "follow the workflow" degrades to "mostly follow the workflow" within a week. An eval is the thing that fails loudly when a step was skipped or a guardrail was crossed.

• Run structural and output evals in CI or as a mandatory post-step. Cheap, deterministic, no excuses.
• Use the LLM judge for the things a script cannot see, but keep its rubric short and specific. A vague judge is a flaky judge, and a flaky judge is worse than none.
• When an eval fails, the workflow run is not done. Not "done with a note".

Orchestration: who runs it#

Something has to sit above the workflows and actually drive them. That is the orchestrator: an agent, or a thin script that calls an agent per step. Its job:

1. Classify the incoming request and select the workflow. If none fits, say so rather than forcing one.
2. Gather the inputs the workflow declares, and refuse to start if a precondition is unmet.
3. Run steps in order. For each step, dispatch a sub-agent scoped to that step's skill and inputs.
4. Update the checklist as outputs land. Keep the workflow file the single source of progress.
5. Block at checkpoints that need human sign-off. Do not proceed on a timeout.
6. Handle failure: retry once with the error in context, then stop and report. Do not improvise past a guardrail.
7. Run the eval at the end and attach the result.

request
   |
   v
orchestrator ---- selects ----> workflows/add-endpoint.md
   |
   |-- step 1 --> sub-agent (skill: api-contract)    --> output, tick box
   |-- step 2 --> sub-agent (skill: endpoint-handler) --> diff, tick box
   |-- step 4 --> [ BLOCK: human approval ]
   |-- step 5 --> sub-agent (skill: changelog-entry)  --> entry, tick box
   |
   v
eval (structural + output + judge) --> pass / fail --> report

One orchestrator for everything is simpler to reason about. Split it per domain only when the routing logic gets genuinely large. Either way, keep the orchestration rules out of the individual workflow files, and log every run: which workflow, which version, which steps ran, what the eval said.

Putting it together#

A request comes in. The orchestrator matches it to workflows/add-endpoint.md, confirms the inputs, and runs the steps. Each step is a scoped sub-agent invoking one skill. Checkboxes fill in as outputs appear. At step 4 the run blocks for a human to approve the auth and rate-limit change. After step 6 the eval verifies the diff stayed in src/api/ and src/schemas/, tests are green, and the changelog entry matches the format. Only then is the run done.

Anti-patterns#

• Workflow docs written as essays instead of checkboxes with outputs.
• Skills that are secretly workflows, with their own phases and approvals.
• No eval, so adherence is assumed rather than checked.
• The orchestrator doing the work itself instead of dispatching, which makes every run a black box.
• Workflows that never get updated when the real process changes, so people quietly stop using them.
• Guardrails phrased as suggestions. "Try not to touch billing" is not a guardrail. "NEVER touch src/billing" is.