gantry: Skill for Claude Code

Adding a Compound Tool — Gantry Proxy

Compound tools orchestrate several game-server calls (with tick waits, retries, verification) behind one MCP tool call. They never talk to the game server directly — they call client.execute(...) the same way handlePassthrough does, just in a loop.

Reality check on existing docs: CONTRIBUTING.md and docs/compound-tools.md both say the canonical implementation lives in compound-tools-impl.ts. That file is now a 34-line re-export shim for backward compatibility — the real code is one file per tool under server/src/proxy/compound-tools/. Use this skill, not those two docs, for the mechanics.

File layout

server/src/proxy/compound-tools/
├── types.ts            # CompoundToolDeps, CompoundResult, GameClientLike
├── utils.ts             # stripPendingFields, waitForNavCacheUpdate, findTargets, isAmmoItem, ...
├── descriptions.ts       # COMPOUND_TOOL_DESCRIPTIONS + COMPOUND_TOOL_NAMES (test-only; dashboard has its own copy, see step 5)
├── index.ts              # barrel — re-exports every tool + types + utils
├── batch-mine.ts          # simplest example — copy this for a straight loop-with-early-exit tool
├── flee.ts                # good example of branching / edge-case handling (phantom-battle detection)
└── <name>.ts              # your new tool

Create server/src/proxy/compound-tools/<name>.ts. One file per tool, named after the tool (snake_case tool name → kebab-case filename, e.g. scan_and_attack → scan-and-attack.ts).

The *Deps pattern

Every compound tool takes CompoundToolDeps (defined in compound-tools/types.ts) as its first argument — never import shared state directly:

export interface CompoundToolDeps {
  client: GameClientLike;                    // execute/waitForTick/isV2/...
  agentName: string;
  statusCache: Map<string, { data: Record<string, unknown>; fetchedAt: number }>;
  battleCache: Map<string, BattleStateForCache | null>;
  sellLog: SellLog;
  galaxyGraph: GalaxyGraph;
  persistBattleState: (agentName: string, state: BattleStateForCache | null) => void;
  upsertNote: (agentName: string, type: string, content: string) => void;
  eventBuffers?: Map<string, { events?: Array<{ type: string }> }>;
}