Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

#2323 Promote CodeBuddy and WorkBuddy from custom-tool configs to first-class Swamp clients

Opened by usefulish · 9/21/2026

Problem

Swamp ships bundled, first-class skills for only four agents — Claude Code (swamp repo init, default), Cursor (--tool cursor), OpenCode (--tool opencode), and Codex (--tool codex). Every other agent has to be wired in manually as a custom tool via .swamp-custom-tools.yaml: the user must hand-author a skillsDir, an instructionsFile, and — crucially — supply a copy of Swamp's own skill content (the swamp / swamp-getting-started SKILL.md bundles), because the binary only bundles skills for the four built-ins.

This is brittle and invisible to newcomers. The custom-tool path duplicates Swamp's skill content outside the binary, so it drifts from the bundled version and each new agent's users must rediscover the boilerplate independently.

Evidence (real use)

While onboarding CodeBuddy to an existing Swamp repo (documentation-factory), the working setup required:

  1. Add codebuddy to tools: in .swamp.yaml.
  2. Add a codebuddy block to .swamp-custom-tools.yaml mirroring the existing workbuddy entry (name, skillsDir, instructionsFile, instructionsMode, skillReferenceStyle, gitignoreEntries).
  3. Copy the Swamp skill bundle into a repo-local .codebuddy/skills/ directory (there is no binary-provided source for a non-built-in tool).
  4. Author .codebuddy/swamp-instructions.md (the swamp-managed instructions block) by hand.

It works, but every non-built-in agent repeats steps 2–4 from scratch, and the skill content copied in step 3 is a snapshot that will fall behind the bundled skills.

Proposed solution

Promote CodeBuddy and WorkBuddy to first-class Swamp clients, giving them the same treatment as the four built-ins:

  • swamp repo init --tool codebuddy / --tool workbuddy (and swamp repo upgrade --tool codebuddy) write the bundled Swamp skills into the tool's conventional skills directory, exactly as --tool codex writes .agents/skills/.
  • The agent's instructions file (e.g. CODEBUDDY.md) receives the swamp-managed section automatically, as CLAUDE.md/AGENTS.md do today.
  • The README's "Using Swamp with AI Agents" tool table is extended (or made data-driven) to list them.

This keeps a single source of truth for skill content in the binary and removes per-agent boilerplate.

Alternatives considered

  • Keep custom tools as-is. Works, but pushes boilerplate onto every non-built-in agent's users and lets skill content drift.
  • Custom-tool scaffolding generator in swamp repo init that emits the .swamp-custom-tools.yaml entry + an empty skills dir, without bundling the skill. Less complete than first-class support — still leaves users to source the skill content.
  • Generic third-party skill discovery (read skills from a configurable dir). Partial fix; doesn't address the duplicated, drifting Swamp skill bundle.

Why it matters

Agent diversity is growing. Treating popular agents as second-class (manual YAML + hand-copied skills) slows adoption and fragments Swamp's skill content across repos. First-class support makes any agent a one-flag setup.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/21/2026, 6:46:29 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.