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):

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.

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. For shared instructions files like AGENTS.md, only the managed section is replaced — your own content is preserved.

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

← PreviousOpenCodeNext →Vaults