workflows-engineering

name

workflows-engineering

description

Use this skill when the user asks about Claude Code Dynamic Workflows, /workflows, ultracode, workflow design, reusable workflow scripts, agentic loops, loop engineering, maker-checker loops, evaluator-optimizer loops, or when to choose workflows versus skills, subagents, MCP, slash commands, hooks, or routines. This skill helps design complex, auditable, observable, repeatable, and optimizable workflows using Claude Code and related primitives.

Workflows Engineering

Use this skill to design Claude Code Dynamic Workflows and related agentic loops.

A workflow is useful when the process is bigger than one chat turn: it needs clear inputs, staged work, parallel subagents, verification, durable artifacts, and a repeatable way to run again. The point is not "more agents." The point is a process that can be inspected, rerun, measured, and improved.

Evidence Discipline

Keep three evidence levels separate:

• Official docs: behavior documented by Anthropic.
• Observed behavior: useful examples from current Claude Code runs. Treat these as implementation clues, not a stable public API.
• Design advice: recommendations for making workflows easier to inspect, test, and improve.

If a path, setting, or UI detail is not in official docs, phrase it as observed behavior or a design recommendation.

Workflow Loop Model

Design workflows as loops with explicit parts:

1. Trigger: what starts the run.
2. Goal: what outcome the run should produce.
3. Inputs: what data, files, URLs, or constraints enter the run.
4. Plan: how the run splits work into phases.
5. Workers: which subagents do bounded tasks.
6. Checks: how results are verified.
7. Stop rule: when the run ends, retries, or asks a person to decide.
8. Artifacts: what proof, reports, or structured files are saved.
9. Metrics: what gets measured for the next version.

Runtime Model

Explain Claude Code Dynamic Workflows in concrete terms:

1. The user asks for a workflow, uses an ultracode trigger, enables a high-effort workflow mode, runs a built-in workflow feature, or invokes a saved workflow command.
2. Claude writes or selects a JavaScript workflow script for the task.
3. Claude Code may show the planned phases and allow the user to inspect the generated script before launch.
4. The workflow runtime executes the script while the main session stays available.
5. The script coordinates phases, logs, subagent calls, parallel fan-out, aggregation, and final return values.
6. Workflow subagents perform the actual reading, writing, shell commands, web fetches, and MCP calls through normal Claude Code permissions.
7. Intermediate results stay in script variables and structured subagent returns instead of filling the main chat.
8. /workflows shows progress, phase state, subagents, token use, elapsed time, recent tool calls, and results.
9. The final result returns to the session. If the run is worth repeating, save it as a workflow command.

The workflow script coordinates work. Subagents use tools. This difference matters for safety, permissions, and debugging.

Script Anatomy

A workflow script usually includes:

• Metadata: name, description, and phase list.
• Input validation from args.
• Prompt builders for subagent roles.
• Structured output schemas.
• Phase markers for progress visibility.
• Parallel fan-out for independent units.
• Aggregation and deduplication.
• Verification or review phases.
• Budget and scope limits.
• Final structured return object.

Conceptual shape:

export const meta = {
  name: "repo-risk-scan",
  description: "Find, verify, and summarize repository risks",
  phases: ["Scope", "Find", "Verify", "Summarize"],
}

phase("Scope")
const input = args || {}
const maxItems = input.maxItems || 20

phase("Find")
const findings = await parallel(workItems.slice(0, maxItems).map(item => () =>
  agent(buildFinderPrompt(item), {
    label: `find:${item.id}`,
    schema: FINDING_SCHEMA,
  })
))

phase("Verify")
const verdicts = await parallel(flatten(findings).map(finding => () =>
  agent(buildVerifierPrompt(finding), {
    label: `verify:${finding.id}`,
    schema: VERDICT_SCHEMA,
  })
))

return {
  findings,
  verdicts,
  metrics: summarize(findings, verdicts),
}

Treat this as a design sketch, not a frozen API reference.

Storage and Inspection

Official docs describe these storage surfaces:

• Session transcripts are plaintext JSONL files under ~/.claude/projects/.
• Session transcripts include messages, tool calls, and tool results.
• Subagent transcripts are stored under the parent session's project directory.
• Large tool results may be stored as separate files.
• Every workflow run writes its generated script under the session directory.
• Saved project workflows live under .claude/workflows/.
• Saved personal workflows live under ~/.claude/workflows/.

Practical inspection map:

~/.claude/projects/
  session transcript files
  subagent transcripts
  large tool outputs
  generated workflow scripts

.claude/workflows/
  project workflow commands

~/.claude/workflows/
  personal workflow commands

Security note: transcripts are plaintext. Do not let tools print secrets or read sensitive files unless you are comfortable with those values appearing in stored transcripts.

Observability

Use two layers of observability:

• Live view: /workflows, phase state, subagent status, token use, elapsed time, recent tool calls, and results.
• Saved artifacts: files written by the run so the result can be checked later.

Recommended artifacts for serious workflows:

runs/<run-id>/
  args.json
  plan.json
  phase-log.jsonl
  agent-log.jsonl
  evidence.jsonl
  decisions.jsonl
  verification.json
  metrics.json
  final-report.md
  improvement-notes.md

If a workflow produces only prose, it is hard to improve. If it has no verification artifact, it is hard to trust. If it has no metrics, it is hard to compare the next run.

Optimization Loop

Improve workflows like software:

1. Start with a small test slice.
2. Capture baseline cost, time, pass rate, false positives, failed checks, and unresolved questions.
3. Add structured artifacts before expanding scope.
4. Change one thing at a time: prompt, schema, phase, model, fan-out count, or check rule.
5. Rerun the same input.
6. Compare metrics.
7. Save the workflow only after it is stable.

Common optimization levers:

• Narrow args.scope before wide runs.
• Add args.max_items, args.max_iterations, and args.dry_run.
• Split planner, maker, reviewer, and writer roles.
• Add a skeptical reviewer instead of trusting the first result.
• Require structured outputs.
• Deduplicate before expensive work.
• Track false positives and failed checks.
• Keep human decisions outside a single uninterrupted run.

Fast Selection

Use a workflow when the task has several of these properties:

• Many independent subtasks can run in parallel.
• Intermediate results would overwhelm the main chat.
• The process should be reused with new inputs.
• The process needs loops, branching, retries, or staged aggregation.
• The output needs proof, artifacts, or independent checks.
• The user wants to inspect, save, rerun, compare, or improve the process.

Use a skill when the task is mostly reusable instructions:

• Teach Claude a procedure, style, policy, domain, or checklist.
• Bundle reference files, templates, scripts, or examples.
• Trigger a compact playbook when relevant.

Use a subagent when the task needs isolation but not a reusable workflow:

• Delegate one bounded research, coding, review, or verification job.
• Keep the main chat clean while a worker handles a scoped task.

Use MCP when Claude needs an external capability:

• Read or update third-party systems.
• Query databases, docs, tickets, design files, or browser state.
• Avoid copying data manually into chat.

Use hooks when a rule must fire automatically:

• Format after edits.
• Block risky commands.
• Run checks at lifecycle points.
• Enforce deterministic policy.

Core Mechanics

Current official mechanics to preserve:

• Dynamic Workflows require a recent version of Claude Code; confirm the minimum version in /config or the current release notes.
• They are available on paid plans and supported API provider setups.
• Some users may need to enable Dynamic Workflows in /config.
• A workflow is a script Claude writes for the task and runs across subagents.
• The script coordinates subagents. Subagents use tools.
• Intermediate results stay outside the main chat context.
• Every run writes its generated script under the session directory.
• The generated script can be inspected, edited, and relaunched.
• Runs are managed from /workflows or the task panel.
• Saved workflows live in .claude/workflows/ or ~/.claude/workflows/.
• Saved workflows run as slash commands and can receive structured input through args.
• Paused runs can resume within the same Claude Code session.
• If Claude Code exits while a workflow is running, the next session starts the workflow fresh.
• Workflows can run up to 16 concurrent subagents and up to 1,000 total subagents per run.
• No mid-run user input is available except permission prompts.
• Large workflow runs can use meaningfully more tokens than a normal conversation.
• Workflow-spawned subagents inherit relevant tool permissions and may prompt or fail when a tool is outside the allowlist.

Decision Matrix

Need	Best primitive	Reason
Reusable multi-agent process with branching	Dynamic Workflow	The process becomes runnable script logic.
Reusable instructions, templates, or policy	Skill	The instructions trigger when relevant.
One isolated specialist task	Subagent	It separates context without building a reusable process.
External system access	MCP	It gives Claude a tool boundary to another system.
Automatic lifecycle rule	Hook	It runs deterministically at configured events.
User-facing command	Saved workflow or skill	Workflows are better for orchestration; skills are better for guidance.
Repeatable scheduled job	Workflow plus an external scheduler	The scheduler starts the job; the workflow performs the process.
Durable audit trail	Workflow artifacts plus a project tracker	Artifacts prove what happened; the tracker holds status.

Workflow Design Procedure

When designing a Claude Code workflow:

1. Define the repeatable goal.
2. Define how input enters through args.
3. Define the input schema and constraints.
4. Define the phases.
5. Identify independent work units.
6. Define maker and reviewer roles.
7. Define the stop rule: success, no progress, max iterations, budget cap, timeout, or human decision.
8. Specify output files and artifact structure.
9. Require source or evidence fields in artifacts.
10. Add a small test mode.
11. Add failure labels.
12. Add final aggregation and skeptical verification.
13. Define metrics for improvement.
14. Define where the script, saved command, and artifacts can be inspected.
15. Define how to compare the next run against the prior run.

Recommended Spec Template

# [Workflow Name]

## Goal
[One sentence describing the repeatable process.]

## Use When
- [Situation 1]
- [Situation 2]

## Do Not Use When
- [A person must decide in the middle of the process]
- [The task is one small bounded delegation]

## Args Schema
```json
{
  "input": "",
  "output_dir": "",
  "dry_run": true,
  "max_items": 10,
  "max_iterations": 3
}
```

## Outputs
- `final-report.md`
- `metrics.json`
- `verification.json`
- `phase-log.jsonl`
- `agent-log.jsonl`
- `evidence.jsonl`

## Phases
1. Validate inputs.
2. Plan the pass.
3. Dispatch makers in parallel.
4. Dispatch reviewers.
5. Decide whether to revise or stop.
6. Write artifacts and metrics.
7. Return summary.

## Subagent Roles
- `planner`
- `maker`
- `reviewer`
- `writer`

## Failure Labels
- `success`
- `partial_success`
- `no_relevant_results`
- `tool_failure`
- `permission_blocked`
- `human_decision_required`
- `no_progress`
- `budget_exceeded`

## Metrics
- `elapsed_seconds`
- `agent_count`
- `token_estimate`
- `items_processed`
- `items_verified`
- `false_positive_count`
- `blocked_count`

## Inspection
- Runtime UI: `/workflows`
- Saved command path: `.claude/workflows/[name]` or `~/.claude/workflows/[name]`
- Session transcript area: `~/.claude/projects/`
- Artifact directory: `[output_dir]/runs/[run-id]/`

Anti-Patterns

• Do not use a workflow just because a task is important. Use it because orchestration should be scripted.
• Do not ask for a workflow without specifying inputs, outputs, phases, and success criteria.
• Do not build a loop without a stop rule.
• Do not let the maker be the only reviewer.
• Do not keep state only in chat.
• Do not optimize without metrics.
• Do not hide human decisions inside a single uninterrupted run.
• Do not fan out to many subagents before proving the workflow on a small slice.
• Do not treat same-session resume as durable cross-session continuity.
• Do not use MCP as a workflow substitute. MCP gives capabilities; workflows coordinate work.
• Do not use a skill as a dumping ground for huge research. Put deeper docs in references/ and keep SKILL.md compact.
• Do not describe storage without separating official documented behavior from observed behavior.
• Do not call a workflow optimized just because it was saved. It is optimized only when metrics improve across comparable runs.

References

Load only the reference needed for the current request:

• references/official-mechanics.md: official feature mechanics, lifecycle, limits, and storage.
• references/design-patterns.md: loop design, phase structure, reviewer patterns, artifacts, and metrics.
• references/primitive-selection.md: when to use workflows, skills, subagents, MCP, hooks, slash commands, or schedulers.
• references/examples.md: standalone workflow examples for research, code review, content analysis, QA, and data extraction.