#455 How-to: Define custom AI agent tools

Problem statement

Users who want to use swamp with AI tools that aren't built-in (e.g. deepAgents, Windsurf, proprietary internal tools) need documentation on how to define custom agent tools via swamp agent setup.

Proposed solution

Add a how-to guide covering:

1. What custom tools are — tools beyond the built-in set (claude, cursor, opencode, codex, copilot, kiro) that get skills + instructions + gitignore scaffolding without code changes to swamp.

2. Prerequisites — what users need to know about their tool before running the wizard:

   • Where the tool reads instructions/rules from
   • Whether it needs a header block (frontmatter) to auto-load rules
   • Where it expects skills/context files to live

3. Walkthrough of swamp agent setup — step-by-step with example output showing the interactive wizard flow.

4. Managing custom tools — swamp agent list and swamp agent rm.

5. Using custom tools — swamp repo init --tool <name> and swamp repo upgrade --tool <name>.

6. Limitations — custom tools get skills, instructions, and gitignore scaffolding but do NOT get:

   • Audit hook generation
   • Doctor diagnostic checks (swamp doctor audit)
   • Harness detection
   • Tool-specific settings (e.g. Claude settings.json, Cursor hooks, Kiro agent config)

   When a custom tool gains enough traction it can be promoted to built-in with full integration.

7. Example: deepAgents — concrete walkthrough showing setup with AGENTS.md (shared mode) and bare skills/ directory.

Alternatives

Could document this in the CLI --help text only, but a how-to guide with examples is more discoverable and covers the nuances (shared vs owned instructions, frontmatter, skills dir conventions).