Skip to main content

DEFINE A CUSTOM AGENT TOOL

Prerequisites

  • Swamp installed
  • Know three things about your tool:
    1. Where it reads instructions or rules from (e.g., AGENTS.md, .toolname/rules/)
    2. Whether it needs a frontmatter header to auto-load rules
    3. Where it expects skills or context files to live

Define the tool

$ swamp agent setup
To set up a custom agent you'll need to know three things about your tool:

  1. Where it reads instructions/rules from (e.g. AGENTS.md, .toolname/rules/)
  2. Whether it needs a header block to auto-load rules (like Cursor's):
       ---
       alwaysApply: true
       ---
  3. Where it expects skills/context files to live

If you have an existing repo where the tool is already configured, point
the scanner at it and swamp will detect what it can.

Agent name: deepagents

Do you have an existing repo where deepagents is set up?
Path (or Enter to skip):

Scanning current repo...
  No existing config detected.

Where does deepagents read rules/instructions from?
  1. AGENTS.md
  2. Other path
> 1

Some tools need a header like this to auto-load rules:
  ---
  alwaysApply: true
  ---
Does deepagents need this? [y/N] N

Skills directory: .deepagents/skills/  (Enter to accept, or type a path):

How should Swamp manage the instructions file?
  1. shared — Swamp writes a managed section; your content outside it is preserved on upgrade
  2. owned — Swamp owns the entire file and overwrites it on upgrade
> 1

Custom agent "deepagents" configured:
  Skills:        .deepagents/skills/
  Instructions:  AGENTS.md (shared)
  Frontmatter:   none

Saved to .swamp-custom-tools.yaml
Run `swamp repo init --tool deepagents` to set up this repo.

If you have an existing repo where the tool is already configured, enter its path when prompted — the wizard scans for instruction files and skills directories automatically.

A ~/-prefixed skills directory (e.g. ~/.deepagents/skills/) installs skills globally and keeps them current via swamp update. A repo-relative path (e.g. .deepagents/skills/) installs skills per-repo only. See global vs repo-relative skill directories for details.

Instruction modes

The wizard asks how Swamp should manage the instructions file. Two modes are available:

  • shared — Swamp writes its rules inside a managed section (# BEGIN swamp managed section / # END swamp managed section). Content you add outside the managed section is preserved on swamp repo upgrade. Use this when the instructions file is shared with your own project-level rules.
  • owned — Swamp owns the entire file and overwrites it on upgrade. Use this when the tool reads from a dedicated file that only contains Swamp rules.

All built-in tools use shared mode. The wizard defaults to shared unless you choose otherwise.

To change the mode after setup, edit .swamp-custom-tools.yaml directly:

# .swamp-custom-tools.yaml
deepagents:
  instructionsFile: AGENTS.md
  instructionsMode: owned
  skillsDir: .deepagents/skills

The next swamp repo upgrade applies the new mode. See AI agent integration for how shared and owned modes work under the hood.

Initialize the repository

Once defined, use the custom tool name with --tool:

$ swamp repo init --tool deepagents
19:52:22.798 INF repo·init Initialized swamp repository at "/path/to/your/repo" (tools: "deepagents")

To add the custom tool alongside an existing built-in tool:

$ swamp repo upgrade --tool claude --tool deepagents

List custom tools

$ swamp agent list
Custom tools (from .swamp-custom-tools.yaml):

  deepagents
    Skills dir:      .deepagents/skills
    Instructions:    AGENTS.md
    Mode:            shared

Remove a custom tool

$ swamp agent rm deepagents
Remove custom tool "deepagents" from .swamp-custom-tools.yaml? [y/N] Removed custom tool "deepagents".

This removes the definition. The on-disk scaffolding (skills directory, instructions file) stays in place — remove those manually if you no longer need them.

Upgrading

$ swamp repo upgrade

The instructions file and skills directory are refreshed with the latest content. In shared mode, only the managed section is replaced — your own content is preserved. In owned mode, the entire file is overwritten.

Refer to the AI agent integration explanation for details on what custom tools receive compared to built-in tools.

← PreviousOpenCodeNext →Vaults