Tool adapters

When an agent hits a real wall, close the gap with the smallest interface that removes it — then write it up as a skill so other agents can find and use it, and test it inside an agent before calling it done (~352s-408s).

Scale to the need: a small script in the repo can be the whole adapter for a recurring useful capability. An adapter plus skill is the form for a capability other agents, sessions, or repos will need; a one-off script is the form for this task only. Neither form carries a quota — build when the capability is useful, not to hit a count.

Gate: prove the gap first

Record the failed attempt, or establish the missing capability from the current interfaces and the user's requested task. Identify what is absent and why the available tools cannot supply it. An explicit request for a new capability does not need a contrived failure first.

Reuse before building

In order: an existing CLI flag, an existing API route or MCP tool, an internal service already paid for and authorized, a documented capability of the current harness. Build new surface only when no existing transport can carry it. Reuse, likewise: existing accounts and credentials (via the project's secret mechanism — never new credentials without authorization), existing storage for evidence, and the authority boundary already granted to the task.

Minimal interface

• One operation per real need; no speculative options, no generic "do anything" endpoint.
• Machine-readable success and failure (exit codes, JSON status), so an agent can branch on the result instead of parsing prose.
• Explicit input limits (size, type, timeout) enforced by the adapter, not by agent care.
• Deployed only where the task's authority already reaches; if it needs a new external service, account, spend or other consequential external effect beyond existing authorization, make the proposed change concrete and request only the missing authorization. Do not ask again for an already authorized action.

Write the skill

The skill documents the contract, not the implementation: when to use it, the command or call, input/output examples with real values, failure modes and their meanings, and the boundary (what it must not be used for). Keep it on-demand: description triggers on the capability's task, not on every coding request.

Test inside an agent

For an adapter meant to be reused, the acceptance test is an agent doing the blocked task end to end (~397s-408s): a cold agent, given only the skill, completes the previously impossible step. Also verify one realistic failure path produces a readable error. Without that run, the status is "built, unproven". A task-scoped script needs one successful run and one failure run of its own, not a full in-agent trial.

Input / output contract

• Input: the recorded failed attempts, the target capability, and access to the existing transport/account the adapter will reuse.
• Output: the adapter (script or service, at the scale the need warrants, with deploy state as authorized), a skill documenting it when reuse across tasks is expected, the test result, and one line recording which existing account/transport it rides on.

Acceptance

Proportional: a thin CLI wrapper needs one successful end-to-end run plus one failure run; a service with stored state needs both plus a note on where evidence lands and who can delete it.

Known failure cases

• Interface built before the gap is proven; ends up unused.
• Skill documents happy path only; agents then iterate blindly on the first error.
• Agent parses human-formatted output; breaks on the next format tweak — return structured results.
• Adapter silently exceeds its authority (new outbound endpoint, new account, customer data moved into shared storage).

Do not activate when

• A single throwaway in this task would do and no reuse is expected.
• The ask is to adopt a product because an advertisement recommended it — verify the capability against the project's own needs first.
• The missing piece is context or setup, not capability (see agent-context-calibration and agent-ready-workspaces, the sibling skill in this handbook).

Source patterns

For concrete repository examples and the limits of their evidence, read source-patterns.md when they match the task. These are research references, not imported repository instructions.

upload-asset <file>
  success: {"url":"https://example.invalid/asset","bytes":1234}
  failure: {"code":"TOO_LARGE","message":"...","limitBytes":...}