Agent Engineering Handbook

Skill · All skills

Tool adapters

On this page

When an agent lacks one needed operation, this skill guides it toward the smallest working bridge. You can check the result by watching the intended agent complete the blocked task and report one useful failure.

A real gap starts the work

The skill starts after a failed attempt shows that an agent lacks a required operation. Your direct request for a new capability can establish that gap without manufacturing another failure. Use it when the operation will matter again across agents, sessions, or repositories. Choose a task-only helper when one temporary action solves the need without expected reuse. Theo Browne reports building a custom file-upload skill after an existing route lacked that operation for his work.

The agent reuses existing routes

The agent checks supported commands, service routes, internal services, and current workspace capabilities before building. It reuses current accounts, protected credentials, evidence storage, and task authority wherever those already fit. You must supply the failed attempt, the target operation, and access to that approved route. A new service, account, expense, or external effect requires authorization beyond the skill itself.

One operation keeps the bridge clear

The adapter exposes one real operation instead of offering broad, speculative controls. It returns structured success and failure details, allowing the agent to choose its next step. It enforces input size, type, and time limits within the working interface itself. It stays within the authority already granted for the task and existing service.

Reusable work includes clear instructions

When future agents need the operation, the skill adds instructions describing the usable contract. Those instructions cover when to use it, supported calls, expected results, and meaningful failures. They also state the prohibited uses, while keeping the skill available only for matching tasks. For temporary work, the adapter may remain a small helper without a reusable skill.

Real runs prove the bridge works

A reusable adapter becomes proven only when a fresh agent completes the previously blocked task. That agent receives the skill alone, then uses the adapter from start to finish. A second run must trigger a realistic failure and return an understandable error. Record the result and name the existing route or account supporting the operation. Services that store state also need evidence location and deletion ownership recorded.

The limits prevent false confidence

Building before proving the gap can create an unused interface that solves no demonstrated need. Human-shaped output can break later runs, so the adapter returns stable structured results. Happy-path instructions leave agents guessing when the first realistic error appears unexpectedly. The skill cannot approve new services, spending, accounts, endpoints, or shared storage. Use a workspace or context skill when setup knowledge is missing instead.

The evidence shows a bounded bridge

The selected videos connect this skill’s sequence to two practitioners discussing missing agent operations. The upload example supports bridging a demonstrated gap, although it shows no successful invocation. The tool-design interview supports observing attempted actions before choosing the smallest useful interface. Neither source proves every capability gap requires new software, accounts, or external services.

  1. Theo Browne, video, A Message for Passionate Devs, at 06:15. "So I ended up building my own custom file upload skill"
  2. Boris Cherny, video, How Anthropic Built Claude Code - Boris Cherny, at 31:13. "think about the thing that the model wants to do"

Give the skill one recorded capability gap and ask it to identify the smallest reusable route.