Turning One-Off Agent Tasks Into Reusable Workflows

To make an AI agent’s multi-step task reusable, save its steps as typed model definitions and a declarative workflow file in your repository, so the next session runs the saved process instead of rebuilding it from a prompt.

You’ve probably had this happen: an agent does a clean release check (tests, build, smoke test, all in the right order), then the session closes and the process is gone with it. The next day you describe it again and get a slightly different version.

This article shows how to keep that process with Swamp. It covers what becomes reusable and what doesn’t, a small release-check workflow, and how the same workflow runs under Claude Code, Cursor, OpenCode or Codex.

Why a Good Agent Run Disappears

An agent session keeps its working process only in the conversation context, so the process ends when the session does. The commands it ran, the order it chose and the checks it added are not saved anywhere the next session can run. What you have left is a chat transcript and whatever files happened to change.

The fix is to turn the agent’s process into files in the repository that get executed. Once the steps live in the repository, you stop re-explaining the task every session, and the agent’s time goes to changes instead of to rebuilding the procedure.

Reusable AI Agent Workflows With Swamp: What Persists and What Doesn’t

Swamp is a command-line tool that stores an agent’s working automation as typed models, YAML definitions, workflows, versioned data and vault references in a .swamp/ directory inside a Git repository. The Swamp README names six core ideas: models, which describe outside systems as types; definitions, which are YAML files that configure one use of a model type; workflows; data; vaults; and tags.

Swamp makes the process repeatable, not the reasoning. Once an agent’s steps are saved as model definitions and a workflow file, later runs execute those saved steps. When the agent creates or edits them, though, its output can differ from one session to the next.

Swamp and MCP do different jobs. MCP connects an agent to tools, as the developer’s guide to the MCP ecosystem explains. Swamp stores and runs the automation the agent builds with those tools, and you can use both together. Swamp runs on your own machine, and any credentials it uses come from the environment of the shell that starts it.

Setting Up Swamp for Your Harness

Install the binary with the official script, then initialise the repository for your harness. The official install script supports macOS and Linux, and release binaries are also published for Windows.

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude Code reads Swamp’s skills from .claude/skills/ and its instructions from CLAUDE.md. Cursor uses .cursor/skills/ and .cursor/rules/swamp.mdc. OpenCode and Codex both use .agents/skills/ and AGENTS.md.

Swamp ships the skills inside its binary and writes them out when you run init, which is how the agent finds them with no extra setup. Shell completions are available through swamp completions <shell>.

A Release-Check Workflow, End to End

A Swamp workflow is a YAML file that lays out jobs as a DAG, and every step calls a method on a model definition. As How Swamp Works explains, each job waits for the jobs it depends on, and steps in the same job run side by side unless one depends on another.

Normally you would ask the agent to create the run-tests, build-artifact and smoke-test definitions. Read the resulting workflow anyway, because it is the file you are approving. The shape below follows the workflow reference. The <method> placeholders are left in on purpose: replace them with the method names your definitions actually expose.

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

In the release-check workflow, tests and build run at the same time. condition.type: succeeded holds the smoke job until both pass. Check the file with swamp workflow validate release-check, then run it:

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run waits until the run finishes (success, failure or cancellation) or pauses at a manual_approval gate. A successful run exits with 0 and anything else exits non-zero, so CI can gate on it. The --tag flag overrides tags at runtime. Every run saves its outputs as versioned data that can’t be changed afterwards, and you can find it again by tag, so a later session can read what happened instead of reconstructing it from chat history. The data query expression comes from the example in How Swamp Works and needs adapting to your model’s fields.

A passing smoke step only proves the endpoint responded. It does not prove the page rendered or that users could finish a flow. Replaying sessions on the staged build is how front-end regressions of that kind become visible.

Moving the Same Workflow Across Harnesses

When a team moves a Swamp workflow across harnesses, what it shares is the model, definition and workflow files. Each harness’s skills directory is gitignored and written by Swamp itself, and swamp repo upgrade --tool <name> lets a developer switch harnesses or run several side by side. The README notes that every tool gets its own skills folder, kept out of Git.

Say the repository was initialised for Claude Code and a teammate uses Cursor. The agent harness changes but the workflow file stays the same:

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run doesn’t depend on which agent invoked it. The agent’s part is writing and editing definitions, and that part changes with the harness. OpenCode and Codex share .agents/skills/ and AGENTS.md, so both tools read the same skills location.

By default, Swamp keeps run data such as model data, workflow runs, outputs and audit logs in .swamp/. Teams that need the same state on several machines can switch to another datastore backend, such as a shared filesystem path or S3. The checkout also moves with you: on a remote box set up for agentic coding, the same workflow runs as long as that shell has the credentials the models need. Use --repo-dir or SWAMP_REPO_DIR to point Swamp at a repository outside the current directory.

Swamp’s Maturity and Limits

Swamp is early tooling. It is actively maintained in the swamp-club repositories and ships continuous date-stamped releases. Plan for change.

• Closed contributions. Only Elder Swamp Club staff write code for Swamp. Pull requests from forks are closed automatically, so bugs and feature ideas go in through swamp issue bug or swamp issue feature, and the maintainers build the ones they accept.
• Telemetry. Swamp collects usage telemetry unless you disable it. You can turn it off for one command with --no-telemetry, for a shell with SWAMP_NO_TELEMETRY=1, for a repository with telemetryDisabled: true in .swamp.yaml, or for every run on your machine with swamp config set telemetry.collection disabled, which writes the setting to ~/.config/swamp/telemetry.yaml.
• Scope. A one-line script or cron job doesn’t need models, a DAG and versioned data. Swamp pays off when a task spans several systems, needs a history, or is shared by a team.
• Extensions run code. Review third-party extensions before you trust them.
• Licence. AGPL-3.0 with the Swamp Extension and Definition Exception.

A deterministic runner repeats a bad workflow just as faithfully as a good one. Assertions and human review are still needed.

Conclusion

Swamp keeps the procedure, not the agent’s thinking. Saved definitions and workflows give you the same steps and the same gates on every run, and the agent stays free (and variable) whenever it writes or changes them. A good next step is to pick one process your agent already does well, such as a release check or a review pass, and ask it to save that process as a Swamp workflow. Review the YAML, commit it, and run it from a second harness to confirm it works there too.

FAQs

How do I run a Swamp workflow in GitHub Actions CI?

Use swamp-club/setup-swamp, the official GitHub Action. It installs Swamp with the official install script and can also sign in to swamp.club if you pass an api-key input. Set repo-init to true to run swamp repo init after the install. A later step calls swamp workflow run with the workflow name. If the run fails, the command exits non-zero and the job fails. The action is still at an early v0.1 release.

Where should secrets for a Swamp workflow be stored?

Put them in a Swamp vault and refer to them by name in definitions and workflows. Swamp fetches the real value at the moment a step runs. That keeps it out of your YAML files and your .swamp data, and nothing is kept for the next run. The built-in local encryption provider needs no extra setup. Other vault providers keep secrets in outside services such as AWS Secrets Manager, Azure Key Vault or 1Password.

Does a Swamp workflow need an AI agent to run?

No. swamp workflow run is an ordinary CLI command, so a developer, a CI job or a script can run a saved workflow without any agent. You only need the agent to create or edit models, definitions and workflows. For runs nobody starts by hand, swamp serve can run a workflow on a cron trigger. It can also run one when a signed webhook arrives from GitHub, Jira, Linear, Stripe, Slack or a generic endpoint.

Can Swamp be installed on Windows?

Yes. Swamp releases on the swamp-club/swamp GitHub releases page include a swamp-windows-x86_64.zip archive that contains swamp.exe, alongside the macOS and Linux builds. The curl one-liner pipes the install script into sh, so it does not work on Windows. Windows users download the release archive, extract swamp.exe and put it in a directory on their PATH.